Skip to content

Knowledge base

Designing efficient agent interfaces

An efficient agent interface keeps tool definitions and intermediate data out of the model's context. Agents do better writing code against a few task-shaped tools, or calling a CLI they already know, than choosing among dozens of tools that wrap every API endpoint.

Written by

Updated:

Tools 4

Our position. We hold that an agent that writes code to call tools (opens in a new tab) beats one making direct tool calls. We keep MCP servers for the few cases where a CLI cannot do the job (opens in a new tab), and for a custom tool we own we build the CLI first, wrapping it in MCP later if the standard is needed.

Why let the agent write code instead of calling tools?

Both Anthropic and Cloudflare converged on the same answer to MCP’s scaling problem: present MCP servers as code APIs and let the agent write code against them instead of making direct tool calls. Anthropic’s version generates a filesystem tree of typed tool wrappers that the agent explores on demand; in their example this cut token usage from 150,000 to 2,000, a 98.7% saving (Anthropic - Code execution with MCP (opens in a new tab)). Cloudflare’s “Code Mode” ships an MCP server for the entire Cloudflare API with just two tools, search() and execute(), holding the context footprint at around 1,000 tokens where an equivalent conventional server would need 1.17 million, more than any current model’s context window (Cloudflare - Code Mode: give agents an entire API in 1,000 tokens (opens in a new tab)).

The pattern fixes both MCP token problems at once. Tool definitions load progressively (the agent reads only the wrappers it needs), and intermediate results stay in the execution environment instead of flowing through the model: an agent can filter a 10,000-row spreadsheet in code and surface five rows, chain loops and conditionals without round-tripping through the agent loop, and even keep PII out of model context entirely via harness-level tokenization (Anthropic - Code execution with MCP (opens in a new tab)). Writing code against an API instead of making individual tool calls cut token usage by 81% when Cloudflare converted an MCP server into a TypeScript API (Cloudflare - Sandboxing AI agents, 100x faster (opens in a new tab), 24 March 2026), and Anthropic’s programmatic tool calling cut average usage on complex research tasks by 37%, from 43,588 to 27,297 tokens (Anthropic - Advanced tool use (opens in a new tab), 24 November 2025).

The cost is infrastructure: agent-generated code needs a sandboxed execution environment with resource limits and monitoring, operational overhead that direct tool calls avoid (Anthropic - Code execution with MCP (opens in a new tab)). Cloudflare runs generated code in V8 isolates with no filesystem, no leakable environment variables, and outbound fetches disabled by default (Cloudflare - Code Mode: give agents an entire API in 1,000 tokens (opens in a new tab)). A useful side effect: working code the agent writes against these APIs can be persisted as reusable functions, which connects directly to the skills concept (Anthropic - Code execution with MCP (opens in a new tab)).

Anthropic’s Programmatic Tool Calling packages the same idea as an API primitive: tools are marked with allowed_callers so the model orchestrates them from a Python script running in a sandboxed code-execution tool, and only the script’s final output returns to context while intermediate tool results are processed inside the sandbox (24 November 2025, vendor claim about its own platform). On a budget-compliance task that would otherwise pour 2,000-plus expense line items into context, the approach reduced consumption from roughly 200KB of raw data to about 1KB of results, and improved accuracy on the GAIA benchmark from 46.5% to 51.2%; it also eliminates one inference round-trip per tool call, which matters when a workflow orchestrates 20-plus calls (Anthropic - Advanced tool use (opens in a new tab)).

Anthropic reports Claude for Excel uses this mechanism to read and modify spreadsheets with thousands of rows without overloading context (Anthropic - Advanced tool use (opens in a new tab)). The tradeoff mirrors the general pattern: it pays off for large datasets, multi-step dependent calls, and parallel operations, but adds needless overhead for simple single-tool lookups (Anthropic - Advanced tool use (opens in a new tab)).

One motivation for the whole approach is that models are trained on billions of lines of code but almost no synthetic JSON tool-calling formats, so expressing orchestration as code tends to beat native tool calls on accuracy (Anthropic developer tools walkthrough (video, February 2026) (opens in a new tab)). Applied to web search, letting Claude write code that filters results before they enter context improved accuracy by about 11% and cut input tokens by about 24% on average across BrowseComp and Deep Search QA, with BrowseComp rising from 33% to 46% for Sonnet and 45% to 61% for Opus (Anthropic developer tools walkthrough (video, February 2026) (opens in a new tab)). A caveat matters for cost accounting: programmatic tool calling does not always reduce the bill, since price-weighted token usage fell for Sonnet 4.6 but rose for Opus 4.6, which wrote more filtering code than the saved output was worth (Anthropic developer tools walkthrough (video, February 2026) (opens in a new tab)).

By February 2026 the pattern was cross-ecosystem rather than Anthropic-specific: it appeared in Cloudflare’s Code Mode (September 2025), shipped in Block’s Goose agent and in LiteLLM’s provider-agnostic support, and has been part of Gemini since Gemini 2.0 (Anthropic developer tools walkthrough (video, February 2026) (opens in a new tab)).

How do you design tools an agent can use well?

When an MCP server does earn its place, how its tools are shaped decides whether an agent uses them well. Anthropic frames a tool as a new kind of software: a contract between a deterministic system and a non-deterministic agent, which means designing for the agent’s affordances rather than copying the function signatures a human developer would want (Anthropic - Writing effective tools for agents (opens in a new tab)). The most common anti-pattern is a server that mechanically wraps every API endpoint; agents have scarce context where computers have cheap memory, so a list_contacts tool that dumps the whole address book forces brute-force reading, while search_contacts or message_contact matches how an agent actually works (Anthropic - Writing effective tools for agents (opens in a new tab), 11 September 2025). The recommended move is consolidation: build a few high-impact tools that each fold several operations into one call, such as a schedule_event that finds availability and books in one step, a search_logs that returns only relevant lines with surrounding context, or a get_customer_context that compiles a customer’s recent records at once, so intermediate outputs never reach the model (Anthropic - Writing effective tools for agents (opens in a new tab)).

Several concrete practices follow. Namespace related tools under common prefixes (asana_search, jira_search) so agents disambiguate among dozens of similarly named tools; prefix versus suffix schemes have non-trivial, model-specific effects worth measuring (Anthropic - Writing effective tools for agents (opens in a new tab)). Return only high-signal fields (name, file_type) and suppress low-level identifiers (uuid, mime_type); resolving opaque UUIDs to semantic names measurably improves retrieval precision and reduces hallucination, and a response_format enum toggling concise versus detailed output can cut a response to roughly a third of its tokens (Anthropic - Writing effective tools for agents (opens in a new tab), 11 September 2025). Cap and paginate large responses (Claude Code truncates tool responses to 25,000 tokens by default) and write error messages that steer the agent toward a valid retry rather than dumping a traceback (Anthropic - Writing effective tools for agents (opens in a new tab)).

The single highest-leverage lever is prompt-engineering the tool description itself: written like an explanation to a new hire, with niche terms and resource relationships made explicit, small refinements can move the needle sharply (precise description edits helped Claude Sonnet 3.5 reach then state-of-the-art SWE-bench Verified performance) (Anthropic - Writing effective tools for agents (opens in a new tab)). Because JSON Schema defines what is structurally valid but not how a tool is meant to be used, Anthropic also added Tool Use Examples: a handful of sample calls attached to a definition that teach date and ID formats, nested-object construction, and which optional parameters correlate, which lifted accuracy on complex parameter handling from 72% to 90% in internal testing (24 November 2025, vendor claim about its own platform) (Anthropic - Advanced tool use (opens in a new tab)).

The meta-technique tying it together is evaluation-driven: prototype the tools, generate realistic multi-step eval tasks, run agents against them, then paste the transcripts back into Claude Code and let the model critique and rewrite its own tools, an approach that beat expert hand-written implementations on held-out test sets (Anthropic - Writing effective tools for agents (opens in a new tab)).

When should you use a CLI or skill instead of MCP?

For many tasks an MCP server is simply the wrong tool. Agents already run Bash and write code well, both of which are composable in ways MCP tool results are not (every MCP result must pass through the agent’s context to be persisted or combined). A handful of small purpose-built scripts documented in a README can replace a 20+ tool browser automation server at a fraction of the context cost, and are extensible by the agent itself (What if you don’t need MCP at all? (opens in a new tab)).

Vercel’s rebuild of its internal text-to-SQL agent d0 is the sharpest data point for the minimalist end of this spectrum. The team deleted roughly a dozen specialized tools (schema lookup, query validation, error recovery, join finders) and left a single tool that executes arbitrary bash, letting Claude Opus 4.5 explore a Cube semantic layer with grep, cat, find, and ls; across five representative queries the file-system agent moved from a 4/5 to a 5/5 success rate, ran 3.5 times faster (274.8s to 77.4s average), used 37% fewer tokens, and took 42% fewer steps (Vercel, December 2025, vendor claim about its own agent). The load-bearing caveat is that the approach only worked because the semantic layer was already well-structured documentation; pointing an agent at a mess of legacy naming and undocumented joins just produces faster bad queries (Vercel - We removed 80% of our agent’s tools (opens in a new tab)).

The general lesson, echoing the fewer-servers guidance on Protocol and context cost, is that every tool is a choice made on the model’s behalf, and a capable model often chooses better when left to reason over raw files (Vercel - We removed 80% of our agent’s tools (opens in a new tab)).

The binary framing is itself questioned, though, which qualifies a CLI-first default. One production team running both reports benchmark results favoring CLI (10 to 32 times better token efficiency, near-100% versus roughly 72% reliability in one 75-comparison study) but settled on a 70/30 split anyway: CLI for execution, MCP for reads and discovery, chosen per integration based on where the tool runs, how it authenticates, and what the workflow demands (The CLI vs MCP Debate Is Asking the Wrong Question (opens in a new tab)).

Skills sit alongside rather than against MCP. Skills operate inside the model’s reasoning with progressive disclosure (only compact frontmatter loads until the skill is used), while MCP tools connect to the world outside; the productive pattern is pairing them, with skills teaching the model how to use MCP or CLI tools effectively (Software Guru - Prompts vs Skills vs MCP Tools vs Agents (opens in a new tab)). The comparative guidance for Claude Code artifacts matches: skills are context-efficient through progressive disclosure, MCP servers are context-expensive because they load on boot, and MCP earns its place specifically for external integrations such as issue trackers and databases (Claude Code).

Every pattern above is an interface an operator builds for their own agent. A conference talk covers the inverse problem, a library or documentation maintainer making themselves legible to agents they do not control. Three practices follow. A hand-written llms.txt of roughly 40 lines outperformed a generated one of about a thousand in the speaker’s own testing. Every documentation page is served with a markdown twin, because an agent fetches rather than browses. And because a coding agent judging a dependency reads the installed package rather than the live site, the same markdown documentation and an agents.md pointer are bundled inside the published package itself. The supporting figures are the speaker’s own product metrics (How We Got LLMs to Recommend Our Open Source Library (opens in a new tab), August 2026, practitioner).

Resources

Agent-facing documentation