The news. On July 9, 2026, the AWS Machine Learning blog published a practical MCP tool-design guide built around the failure modes behind underperforming agent tools: context bloat and model confusion. It compares six versions of one local MCP server, all over the same K-12 search backend — moving from a raw API passthrough, through richer descriptions, schema constraints, and lazy-loaded taxonomy, to server-side introspection and a full agent-as-tool endpoint — and frames the whole exercise as context engineering. Read the guide →
Think about briefing a new assistant before you hand off a task. You could drop the entire company wiki on their desk and say "figure out the K-12 search" — technically everything they need is in there. But they'll spend the morning reading, and when they finally act they'll misfile half of it. A good manager does the opposite: a one-page checklist with the handful of options that matter, the thick reference binder handed over only when a task actually needs it, and for the routine errands, "just handle the whole booking." That difference — how much you make someone read before they can act — is exactly what AWS calls tool design, and it lands on the agent as context engineering. An agent's tool isn't just a function it calls; it's text the model must read and reason over first, and every wasted line competes for the same scarce context it needs for the actual problem.
The guide's opening version is the "drop the whole wiki" move: raw API passthrough, where the MCP server simply re-exposes the backend and lets the model sort out fourteen filterable fields on its own. It works in a demo and frays in production — the model calls the wrong filter, or reads back a fifty-field record when it needed five. The fix is not a smarter model but a better-designed tool, and AWS's knobs are the same ones a good manager uses on that briefing note. Write descriptions and errors a reader can actually act on. Constrain the schema — finite enums, sane defaults, and a rule of thumb of around eight parameters or fewer per tool, splitting a broad do-everything tool into focused ones the model can't misaim.
Then trim what comes back. A high-leverage move is refusing to hand the model a fifty-line report when a five-field checklist would do: defaulting a bloated response down to its key fields is a response the model reads in a fraction of the tokens. And instead of loading the entire filter taxonomy up front, lazy-load it — keep the reference binder closed until a query needs it. Past that, two heavier moves shift reasoning off the model: server-side introspection, where a server-controlled model interprets the request, and the endpoint of the whole progression, agent-as-tool — one natural-language endpoint behind which a server-owned agent runs the taxonomy lookup, search, detail retrieval, memory, and formatting itself. The calling model stops seeing a toolbox and sees a single competent helper.
Where the tokens actually go
Here is the arithmetic that makes "context engineering" concrete rather than a slogan. Take a single result record from that backend. Version one hands the model every field the record has; default that response down from 50 fields to the 5 the task needs and the guide reports the response cost drops by roughly two-thirds — the same record, a third of the reading. Stack the other knobs on top: keep each tool to about 8 parameters or fewer so the call itself is small and hard to malform, and lazy-load the long filter taxonomy so the model reads it only when a query needs it — a move Anthropic reports can cut tool-definition tokens by up to 85%. None of this changes the backend's 14 filterable fields; it only changes how much the model has to read to use them — which is the whole difference between an agent that reasons about the task and one that spends its context budget reading a manual.
| Design move | What the server does | Effect on the model's context |
|---|---|---|
| Raw API passthrough | re-expose the backend API as-is | model reads every endpoint + all 14 fields itself |
| Clear descriptions & errors | plain-language docs, actionable error text | fewer wrong calls, less retry churn |
| Schema constraints | finite enums, defaults, focused tools | ~8 params or fewer (AWS rule of thumb); call is hard to malform |
| Response field defaulting | return ~5 key fields, not all ~50 | ~⅔ fewer response tokens (per the guide, setup-dependent) |
| Lazy-loaded taxonomy | load the filter list only when needed | up to ~85% fewer tool-def tokens (Anthropic, setup-dependent) |
| Agent-as-tool | one NL endpoint; a server-side agent runs the steps | model sees one tool, not a toolbox |
The ladder is not "always go to the last rung." Each step trades model-side flexibility for a smaller, cleaner context and more server-side control — a classic cost-and-latency call you make per tool, not once for the whole system.
Goes deeper in: AI Agents → Tool Use → Tool Design — ACI + Anti-Patterns
Related explainers
- MCP SEP-2663 — async task handles — the protocol side of the same story: how an MCP server returns a Task handle so long-running tool calls don't block the agent
- ToolFailBench — tool-use failure taxonomy — what goes wrong when an agent uses a tool badly; this guide is about designing the tool so it can't
- Tool-router — contextual-bandit tool routing — once you have many well-designed tools, how the agent learns which provider to call