refactor: consolidate 47 tools into 8 unified action-based tools

[jmccardle]

I noticed that this MCP server took up ~16% of context every single conversation, even though I mostly only used it to read/write issues. I used almost every action occasionally, but EVERY session was losing thousands of tokens to tools I wouldn't use.

I wrote this refactor to provide a "user manual" tool so that the LLM can read detailed instructions for whichever specific task it's trying to do, and each task supports multiple target objects. I reduced the amount of explanation in the tools' description because LLMs being used to develop software already understand what issues, repositories, and wiki pages are. Lastly, the error messages are designed to give specific, actionable, token-cheap responses that guide the LLM towards making a correct tool call on the second attempt.

Reduces MCP tool token consumption by 82% (32.7k → 5.7k tokens).

New unified tools:

• gitea_manual: On-demand documentation lookup (lazy-loaded)
• create_gitea: Create resources (issue, label, milestone, etc.)
• get_gitea: Get single resource details
• list_gitea: List resources with filtering
• edit_gitea: Edit existing resources
• delete_gitea: Delete resources
• link_gitea: Create relationships (labels, dependencies)
• unlink_gitea: Remove relationships

Key design decisions:

• Action-based organization leverages LLM implicit knowledge
• Lazy documentation via gitea_manual avoids upfront token cost
• Rich error messages include relevant schema for self-correction

🤖 Generated with Claude Code

[jmccardle]

I think the "manual" pattern is pretty interesting - it gives agents like Claude the opportunity to request focused documentation rather than having documentation in context unconditionally.

[scs3jb]

Is this PR the best option for reducing context? I dont see as high context taken as above.

     Loaded
     ├ mcp__forgejo__add_issue_labels: 212 tokens
     ├ mcp__forgejo__create_issue: 422 tokens
     ├ mcp__forgejo__create_issue_comment: 197 tokens
     ├ mcp__forgejo__create_label: 249 tokens
     ├ mcp__forgejo__create_milestone: 274 tokens
     ├ mcp__forgejo__edit_issue: 438 tokens
     ├ mcp__forgejo__edit_label: 267 tokens
     ├ mcp__forgejo__get_issue: 187 tokens
     ├ mcp__forgejo__list_repo_issues: 717 tokens
     ├ mcp__forgejo__list_repo_labels: 162 tokens
     └ mcp__forgejo__list_repo_milestones: 230 tokens

[jmccardle]

Is this PR the best option for reducing context? I dont see as high context taken as above.

     Loaded
     ├ mcp__forgejo__add_issue_labels: 212 tokens
     ├ mcp__forgejo__create_issue: 422 tokens
     ├ mcp__forgejo__create_issue_comment: 197 tokens
     ├ mcp__forgejo__create_label: 249 tokens
     ├ mcp__forgejo__create_milestone: 274 tokens
     ├ mcp__forgejo__edit_issue: 438 tokens
     ├ mcp__forgejo__edit_label: 267 tokens
     ├ mcp__forgejo__get_issue: 187 tokens
     ├ mcp__forgejo__list_repo_issues: 717 tokens
     ├ mcp__forgejo__list_repo_labels: 162 tokens
     └ mcp__forgejo__list_repo_milestones: 230 tokens

back in December of 2025, we didn't have dynamic MCP tool context. What you're seeing now is a brief description of the tool, and the agent can pull in the full description of the tool when it decides the tool is relevant. 5-6 months ago, the full tool instructions were available to the model, totaling 32k tokens.