MCP & agent ergonomics: token-efficiency and missing affordances

Executive summary

Synapse’s MCP surface is correct and safe (propose/accept is solid) but not yet optimised for token cost or agent ergonomics. Three cheap fixes pay off immediately: bound the one unbounded read (list_by_type), return structuredContent + compact JSON instead of pretty-printed text, and attach ResourceLinks to reads (entities are already exposed as resources, but tools don’t link to them). Beyond that, a small set of new affordances (a batch read, a workspace-overview digest, a recent_changes delta tool, and batch proposals) would cut the round-trips and exploratory reads that dominate an agent’s token budget. The strategic bet is the Anthropic code-execution-with-MCP pattern (intermediate data never enters context) and shipping Synapse as a one-install Claude plugin (skill + MCP + hooks).

1. Context and premisses

v0.5 ships 15 MCP tools (4 local read, 4 federation read, reindex, replay_proposal, 5 write proposals). Responses are built by mcp::helpers::json_content → serde_json::to_string_pretty wrapped as a text content block. Entities, the manifest, the server-card and recent audit are exposed as resources (synapse://entity/{type}/{id}, paginated). The propose/accept invariant (BR-12.3) is enforced in core::pending::enqueue. The freshness banner is conditional (only when a noteworthy signal exists): already well-behaved.

Assumed: agents are the primary consumer of the MCP door, and their token budget is the scarce resource. The SKILL.md/LLM.md (v0.5, in synapse-releases) already teach correct usage; this brief is about making the server cheaper, not just the docs.

2. Market scan

2.1 Anthropic: writing effective tools for agents

Core principles: avoid tool overload / overlapping tools; namespace related tools; implement response constraints (pagination, range, filtering, truncation with sane defaults) for anything that could flood context; tool descriptions are load-bearing and should be prompt-engineered.

What this means for Synapse: list_by_type violates the response-constraint principle: it takes only type + status, no limit/cursor (src/mcp/args.rs ListArgs), so a big workspace returns everything. search_knowledge and federated_search already cap with limit; list_by_type is the outlier. Fix first.

2.2 MCP 2026 spec: structuredContent, outputSchema, resource links

Tools may return structuredContent (machine-readable JSON conforming to an outputSchema) alongside text; clients parse it programmatically instead of the model re-reading a text blob. Results may carry ResourceLink/EmbeddedResource blocks pointing at resources the client can fetch (and cache) lazily.

What this means for Synapse: today every tool returns pretty-printed JSON as text (json_content). Two wins: (a) emit structuredContent + a tool outputSchema, and drop the pretty-print (whitespace is pure token waste); (b) since entities are already resources, have search_knowledge hits and get_entity return a ResourceLink to synapse://entity/{type}/{id} so a resource-caching client can avoid re-fetching, and the agent can defer reading the body until it’s sure it needs it.

2.3 Anthropic: code execution with MCP (the 98% pattern)

Presenting MCP servers as a code API the agent writes against: loading only the tools it needs and keeping intermediate results in the execution environment: cut token usage by up to 98% in Anthropic’s tests. The “Tool Search Tool” discovers tools on demand (~85% reduction) so the full tool catalogue isn’t loaded upfront.

What this means for Synapse: the CLI analog already exists and is the right shape: syn export --as json | jq '…' filters/aggregates outside the model’s context. The MCP door has no equivalent: an agent must pull data into context to filter it. A constrained, read-only query tool (a safe expression over the workspace JSON, or a thin jq-like projection) would let agents compute answers without the rows entering context. This is the highest-leverage bet.

3. Cross-check vs the current server

4. Positioning

The moat is local-first + auditable propose/accept. No SaaS competitor can match “the model proposes, the human signs off, every write is provenance-stamped and replayable” while keeping data on the laptop. Token-efficiency and agent ergonomics are table stakes that make the moat usable; they are not the moat. Lane to occupy: “the second brain agents drive cheaply and can’t silently corrupt.”

5. Recommendation

Non-goals for now: protocol-level changes; a full code-execution sandbox; dropping any existing tool.

6. Disruptive bets

1. Compute-out-of-context query: a safe, read-only projection/aggregation over the workspace (jq-subset or a whitelisted expression) so an agent answers “how many blocked tasks per owner” without a single row entering its context. The local-first design makes this safe (no remote data exfil) in a way a SaaS MCP cannot casually offer.
2. Synapse as a one-install Claude plugin: .claude-plugin/plugin.json bundling the skill + the MCP server config + hooks (e.g., a SessionStart hook that runs syn doctor/syn pending list). One cp/marketplace install wires the whole loop. Agents that don’t speak MCP still get the skill.
3. Proposal “context snapshot” as a first-class agent contract: every write tool already accepts context; lean into it so syn audit replay can re-run a proposal against a newer model and flag drift. This is an auditability feature no hosted assistant offers: sell it.
4. recent_changes as the agent’s memory diff: a recurring agent (daily standup, weekly review) reads only what changed since its last run; pair with a server-issued cursor so the agent is stateless.

7. Ticket sketch (provisional IDs)

8. Risk register

9. Open decisions

1. Adopt structuredContent now, or wait until the dominant client (Claude Code) renders it? (Recommend: dual-emit now: cost is low.)
2. Is the query tool worth the security surface, or is syn export --as json | jq (CLI) enough and we just teach agents to shell out? (Spike SYN-183 to decide.)
3. Namespace the tools (synapse_*) now (breaking for existing configs) or at v1.0 with the frozen MCP surface?
4. Should workspace_overview and recent_changes be tools or resources (or both)? Resources are cacheable; tools are discoverable.

10. References

• Writing effective tools for AI agents: Anthropic
• Code execution with MCP: Anthropic
• Advanced tool use: Anthropic
• MCP spec: Tools (structuredContent / outputSchema)
• Agent Skills open standard · llms.txt
• Code: src/mcp/{server,helpers,resources,freshness,args}.rs, src/core/mcp/*.rs.