Claude/optimize agor mcp tokens ta nn k#14
Merged
Conversation
External orchestrators (Hermes, etc.) were triggering rapid context compaction because the MCP surface was bloated at multiple layers: - Tool responses were pretty-printed with 2-space indentation (JSON.stringify(_, null, 2)), inflating every payload 30-40%. - SERVER_INSTRUCTIONS carried ~1.8 KB of domain lists and workflow examples on every initialize. - agor_artifacts_publish embedded ~1.6 KB of CONFIG CONVENTION docs in its description; useLocalBundler and artifacts_status carried hundreds more chars each. - Session tools had prose-heavy enum/parameter descriptions (sessionType parentheticals, spawn/prompt narratives, get_current_context field list). - Worktree tools defaulted _include_sessions:true on every get, scaling response size with session count, and othersCan/ othersFsAccess fields repeated tier documentation. - Search/execute meta-tools had long self-descriptions and returned unused hint + domains blobs on every call. Trim every layer. No tool names or schemas removed — only description length, default includes, and response formatting. DOMAIN_DESCRIPTIONS collapsed. agor_worktrees_get now takes an opt-in includeSessions flag (default: false). Expected ≥50% reduction in per-call token cost for typical workflows.
Two related bugs found while reviewing the MCP surface:
1. Pagination was unbounded. `PAGINATION.DEFAULT_LIMIT = 10_000` in
packages/core — every MCP list tool whose description claimed
"default: 50" actually returned up to 10,000 rows because nothing
set $limit when the agent omitted it. Affected: sessions, worktrees,
boards, tasks, repos, users. Set an explicit default of 50 in each
tool handler so the schema's stated default is actually enforced.
2. Archived items leaked into several tools by default:
- agor_cards_list: three code paths (findByZoneId, findByCardTypeId,
unfiltered find) never passed archived=false. Unified on the
includeArchived/archived opt-in pattern (same as sessions/boards)
and added post-filter for the paths where the repo doesn't accept
an archived arg.
- agor_tasks_list: tasks have no archived column and the tool didn't
join to sessions, so tasks from archived sessions were returned.
When called without sessionId, scope to active-session IDs. Added
an includeArchived opt-in.
- agor_messages_list: unscoped search bled into archived sessions.
When no sessionId/taskId is given, restrict via inArray on active
session IDs. Added an includeArchived opt-in.
These are semantic (correctness) fixes as much as token fixes — once a
user archives something, it should stay out of agent context by
default.
Donach
commented
Apr 19, 2026
Comment on lines
+93
to
+95
| const SERVER_INSTRUCTIONS = `Agor MCP uses progressive tool discovery. Two meta-tools are listed: | ||
| - agor_search_tools: browse/filter tools. No args = domains overview. Use detail:"full" to fetch inputSchema. | ||
| - agor_execute_tool: invoke any tool by name. Args go under \`arguments\` (or flattened at top level).`; |
Author
There was a problem hiding this comment.
This trimming seems too aggressive - this seems to lose a lot of useful context.
Author
There was a problem hiding this comment.
Fair — reverted in 22adb03. Kept the workflow recipes (orient / create-and-start / spawn / prompt modes) and a one-line product description, dropped just the redundant domain list (agents get that from agor_search_tools anyway). ~900 bytes vs the original ~1,800 and the over-trimmed ~300.
Generated by Claude Code
Review feedback: the previous trim dropped the workflow recipes which genuinely save agents discovery round-trips. Keep the three common workflows (orient, create-and-start, delegate, continue/fork) and a one-line product description — agents still get the domain listing from agor_search_tools itself, so that part stays out. ~900 bytes vs the original ~1,800 and the over-trimmed ~300.
Donach
added a commit
that referenced
this pull request
Apr 25, 2026
* perf(mcp): slash token cost of Agor MCP server
External orchestrators (Hermes, etc.) were triggering rapid context
compaction because the MCP surface was bloated at multiple layers:
- Tool responses were pretty-printed with 2-space indentation
(JSON.stringify(_, null, 2)), inflating every payload 30-40%.
- SERVER_INSTRUCTIONS carried ~1.8 KB of domain lists and workflow
examples on every initialize.
- agor_artifacts_publish embedded ~1.6 KB of CONFIG CONVENTION docs
in its description; useLocalBundler and artifacts_status carried
hundreds more chars each.
- Session tools had prose-heavy enum/parameter descriptions
(sessionType parentheticals, spawn/prompt narratives,
get_current_context field list).
- Worktree tools defaulted _include_sessions:true on every get,
scaling response size with session count, and othersCan/
othersFsAccess fields repeated tier documentation.
- Search/execute meta-tools had long self-descriptions and returned
unused hint + domains blobs on every call.
Trim every layer. No tool names or schemas removed — only description
length, default includes, and response formatting. DOMAIN_DESCRIPTIONS
collapsed. agor_worktrees_get now takes an opt-in includeSessions
flag (default: false).
Expected ≥50% reduction in per-call token cost for typical workflows.
* fix(mcp): enforce list limits + default-exclude archived everywhere
Two related bugs found while reviewing the MCP surface:
1. Pagination was unbounded. `PAGINATION.DEFAULT_LIMIT = 10_000` in
packages/core — every MCP list tool whose description claimed
"default: 50" actually returned up to 10,000 rows because nothing
set $limit when the agent omitted it. Affected: sessions, worktrees,
boards, tasks, repos, users. Set an explicit default of 50 in each
tool handler so the schema's stated default is actually enforced.
2. Archived items leaked into several tools by default:
- agor_cards_list: three code paths (findByZoneId, findByCardTypeId,
unfiltered find) never passed archived=false. Unified on the
includeArchived/archived opt-in pattern (same as sessions/boards)
and added post-filter for the paths where the repo doesn't accept
an archived arg.
- agor_tasks_list: tasks have no archived column and the tool didn't
join to sessions, so tasks from archived sessions were returned.
When called without sessionId, scope to active-session IDs. Added
an includeArchived opt-in.
- agor_messages_list: unscoped search bled into archived sessions.
When no sessionId/taskId is given, restrict via inArray on active
session IDs. Added an includeArchived opt-in.
These are semantic (correctness) fixes as much as token fixes — once a
user archives something, it should stay out of agent context by
default.
* fix(mcp): restore workflow hints in SERVER_INSTRUCTIONS
Review feedback: the previous trim dropped the workflow recipes which
genuinely save agents discovery round-trips. Keep the three common
workflows (orient, create-and-start, delegate, continue/fork) and a
one-line product description — agents still get the domain listing
from agor_search_tools itself, so that part stays out.
~900 bytes vs the original ~1,800 and the over-trimmed ~300.
---------
Co-authored-by: Claude <noreply@anthropic.com>
Donach
added a commit
that referenced
this pull request
May 1, 2026
* perf(mcp): slash token cost of Agor MCP server
External orchestrators (Hermes, etc.) were triggering rapid context
compaction because the MCP surface was bloated at multiple layers:
- Tool responses were pretty-printed with 2-space indentation
(JSON.stringify(_, null, 2)), inflating every payload 30-40%.
- SERVER_INSTRUCTIONS carried ~1.8 KB of domain lists and workflow
examples on every initialize.
- agor_artifacts_publish embedded ~1.6 KB of CONFIG CONVENTION docs
in its description; useLocalBundler and artifacts_status carried
hundreds more chars each.
- Session tools had prose-heavy enum/parameter descriptions
(sessionType parentheticals, spawn/prompt narratives,
get_current_context field list).
- Worktree tools defaulted _include_sessions:true on every get,
scaling response size with session count, and othersCan/
othersFsAccess fields repeated tier documentation.
- Search/execute meta-tools had long self-descriptions and returned
unused hint + domains blobs on every call.
Trim every layer. No tool names or schemas removed — only description
length, default includes, and response formatting. DOMAIN_DESCRIPTIONS
collapsed. agor_worktrees_get now takes an opt-in includeSessions
flag (default: false).
Expected ≥50% reduction in per-call token cost for typical workflows.
* fix(mcp): enforce list limits + default-exclude archived everywhere
Two related bugs found while reviewing the MCP surface:
1. Pagination was unbounded. `PAGINATION.DEFAULT_LIMIT = 10_000` in
packages/core — every MCP list tool whose description claimed
"default: 50" actually returned up to 10,000 rows because nothing
set $limit when the agent omitted it. Affected: sessions, worktrees,
boards, tasks, repos, users. Set an explicit default of 50 in each
tool handler so the schema's stated default is actually enforced.
2. Archived items leaked into several tools by default:
- agor_cards_list: three code paths (findByZoneId, findByCardTypeId,
unfiltered find) never passed archived=false. Unified on the
includeArchived/archived opt-in pattern (same as sessions/boards)
and added post-filter for the paths where the repo doesn't accept
an archived arg.
- agor_tasks_list: tasks have no archived column and the tool didn't
join to sessions, so tasks from archived sessions were returned.
When called without sessionId, scope to active-session IDs. Added
an includeArchived opt-in.
- agor_messages_list: unscoped search bled into archived sessions.
When no sessionId/taskId is given, restrict via inArray on active
session IDs. Added an includeArchived opt-in.
These are semantic (correctness) fixes as much as token fixes — once a
user archives something, it should stay out of agent context by
default.
* fix(mcp): restore workflow hints in SERVER_INSTRUCTIONS
Review feedback: the previous trim dropped the workflow recipes which
genuinely save agents discovery round-trips. Keep the three common
workflows (orient, create-and-start, delegate, continue/fork) and a
one-line product description — agents still get the domain listing
from agor_search_tools itself, so that part stays out.
~900 bytes vs the original ~1,800 and the over-trimmed ~300.
---------
Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.