Tools and MCP¶
An agent without tools is an expensive chatbot. Tools are the agent's hands. Tool design often matters more than model choice.
Tool anatomy¶
A well-designed tool has five parts:
- Name:
verb + noun, e.g.get_calendar,place_order. This is the first thing the model sees. - Description: what the tool does, when to call it, and any preconditions. Use positive instructions:
"Check the budget with get_budget first"works better than"Do not call without checking the budget". - Parameters: a strict JSON schema with types, bounds, and defaults. Defaults prevent the model from inventing values.
- Response: structured JSON the model can parse.
- Errors: an actionable message, not a generic string.
"Budget exceeded: current 4500, limit 4000. Suggest reducing the order."tells the model what to do next.
Schema constraints, response shaping, and single-purpose tools¶
A model reasons only from what the tool interface exposes. The interface — name, description, parameter schema, and return shape — should remove ambiguity before the model makes a choice [MachineLearningMastery, 2026].
Single-purpose tools¶
Avoid multi-action tools where an action parameter switches between create, read, update, and delete. The model should not have to solve the API design problem before it solves the user's problem.
| Avoid | Prefer |
|---|---|
manage_customer(action, customer_id, data) |
create_customer, get_customer, update_customer, suspend_customer |
execute_command(command: str) |
file_reader, file_writer, service_restarter (scoped to a list) |
Tight schemas¶
Use typed JSON Schema with required/optional distinctions, enum or Literal for finite values, sensible defaults, and bounds. AWS recommends keeping parameter counts around eight or fewer [AWS, 2026].
| Anti-pattern | Better approach |
|---|---|
Internal column names like content_bucket |
LLM-friendly names like resource_class with values 'Student Resource', 'Teacher Support' |
| Optional fields with no defaults | Defaults for the most common case, e.g. language='en', limit=20 |
| Returning every database column by default | Return a compact view; offer a get_resource_detail tool for the full view |
Response shaping¶
A tool that returns 50 fields per result fills context quickly. Returning only the fields the model needs by default, with a detail tool for drill-down, can cut response tokens by roughly two-thirds [AWS, 2026]. Include a defaults_applied field so the model knows what was filtered implicitly.
For empty results, return guidance, not silence:
{
"status": "empty",
"suggestion": "No resources found. Try broadening the subject filter or call get_taxonomy(subject='...') for valid values."
}
Tool count and just-in-time instructions¶
Shopify's Sidekick showed three tool regimes:
| Tool count | Behavior |
|---|---|
| 0–20 | Clear, easy to debug. |
| 20–50 | Boundaries blur; combinations cause unexpected outcomes. |
| 50+ | "Death by a thousand instructions" — the system prompt becomes unwieldy. |
The fix is just-in-time instructions: tool-specific guidance rides back inside the tool response, only when the tool is called. This keeps the system prompt small and preserves prompt caches.
MCP: a standard, not a shortcut¶
MCP (Model Context Protocol) standardizes host-client-server tool wiring. The protocol is not the hard part; the hard part is what the tool does when the backend returns:
- timeouts,
- empty results,
- partial results,
- 5xx errors,
- stack traces.
Before wrapping a backend as an MCP server, walk through every failure path and design a response the model can act on. Automatic wrappers cover the happy path; production is everything else.
MCP production realities¶
By early 2026 there were over 10,000 active MCP servers and 97 million monthly SDK downloads, yet the protocol still leaves three primitives undefined: identity propagation, adaptive timeout budgeting, and structured error semantics [Srinivasan, 2026].
| Production gap | Why it matters | What to do |
|---|---|---|
| Identity propagation | MCP JSON-RPC does not carry user/tenant/permissions by default; a server may return the wrong user's data. | Insert a broker or gateway that injects identity before the server sees the request. |
| Timeout budgeting | A chain of tool calls must fit inside the planner's turn budget. | Target p99 latencies: read-only <500ms, moderate queries <2s, writes <5s; anything >10s should be an async MCP Task [Srinivasan, 2026]. |
| Structured errors | The isError boolean is not enough; the agent will guess what to do. |
Return machine-readable fields: retryable, retry_after, suggested_action, field. |
Other field lessons [TreeRouter, 2026]:
- Verbose definitions in 20+ servers can consume 60,000+ tokens before the first user query. Keep tool descriptions under ~50 characters, schema fields ≤5, and move detail to resources or code-execution mode.
- SSE transports leak file descriptors if connections are not cleaned up; add weakref tracking, one-hour timeouts, and reverse-proxy connection controls.
- Async tasks need cancellation and a polling rate limit; the server should terminate tasks that are not polled within a TTL.
- Expose
/healthand/ready, emit per-tool latency and success metrics, and require idempotency keys for every write tool [Srinivasan, 2026].
Common tool failure modes¶
The model's behavior depends heavily on what a failing tool returns. Generic errors cause the model to either give up or guess again [MachineLearningMastery, 2026].
| Failure | Bad response | Better response |
|---|---|---|
| Empty result | [] |
{"status": "empty", "suggestion": "Try broadening the query or call get_taxonomy(subject='...') for valid values."} |
| Partial result | silently truncated | {"status": "partial", "count": 50, "total": 247, "next_page": "..."} |
| 429 rate limit | Rate limit exceeded |
{"retryable": true, "retry_after": 12, "action": "wait 12s and retry"} |
| 5xx upstream | Internal server error |
{"retryable": true, "suggested_action": "Retry once; if the error persists, route to fallback provider."} |
| Invalid parameter | Bad request |
{"field": "date", "error": "date must be ISO-8601 and not in the future"} |
| Unauthorized | Unauthorized |
{"status": "forbidden", "required_scope": "calendar:write", "action": "escalate to user approval"} |
Tool design checklist¶
- Is the name a
verb + noun? - Does the description say when and under what conditions to call it?
- Are parameter schemas strict and defaults provided?
- Do error messages explain what happened and what to do next?
- Have you tested the failure paths?
Deeper dive: MCP and tool wiring in production¶
MCP is only the envelope; the harder decisions are transport, lifecycle, and how the tool surface maps to your backend. Pontil's 2026 guide recommends choosing between stdio and Streamable HTTP before writing any code: stdio fits a single-host child process, while Streamable HTTP is the minimum for remote agents, central observability, and server-held credentials [Pontil, 2026]. The older HTTP+SSE transport was deprecated in March 2025, and the 2026-07-28 v2 release candidate is moving the protocol toward stateless request/response, so production deployments should stay on the 2025-11-25 spec unless they are explicitly testing v2 [Kerkhoff, 2026]. Supporting both transports on day one is a trap—the auth model, lifecycle, and deployment shape differ enough that you end up maintaining two servers that share a name [Pontil, 2026].
Tool design is the next failure mode. Do not mirror a REST API one-to-one; agents reason by tool name, description, and schema, so a handful of task-shaped tools outperforms dozens of endpoint-shaped CRUD wrappers [Pontil, 2026]. Pontil suggests writing descriptions for an engineer who has never seen the product, keeping descriptions around 50 characters and schemas to five or fewer fields, and moving detail into resources or code-execution mode [Pontil, 2026]. That aligns with the wider 2026 guidance to validate every input with Zod, Pydantic, or a Standard Schema library, keep tool calls idempotent, and never depend on in-memory MCP session state for authorization or billing [Kerkhoff, 2026].
Authentication and observability turn a working server into a production surface. For stdio servers, credentials arrive through environment variables or host config—fail fast at startup if they are missing. For remote servers, the MCP authorization spec treats the server as an OAuth 2.1 resource server: clients discover the authorization endpoint via /.well-known/oauth-protected-resource, complete a PKCE flow, and present a bearer token scoped to a resource indicator [Pontil, 2026]. The server must map that token to a user and invoke the backend as that user; running every tool call as a shared service account breaks permissions, audit, and multi-tenancy [Pontil, 2026]. Log each invocation with timestamp, tool name, authenticated user, redacted arguments, backend latency, and status into your existing observability stack, and wire contract tests, schema validation, and a canary tool call into the same CI pipeline as your backend so backend changes do not silently produce plausible-but-wrong tool responses [Pontil, 2026].
Common wiring mistakes to catch before production include:
- Writing to
stdoutin astdioserver—stdout is the JSON-RPC channel; log tostderrinstead. - Using one service account for all tool calls—delegate identity per request.
- Skipping MCP Inspector and sending the first real query through an agent trace.
- Shipping without contract tests; backend drift becomes a silent data-integrity bug.
- Returning raw backend errors instead of structured, actionable JSON.
References¶
- AWS. "MCP tool design: practical approaches and tradeoffs." Jul 2026. https://aws.amazon.com/blogs/machine-learning/mcp-tool-design-practical-approaches-and-tradeoffs/
- Machine Learning Mastery. "AI Agent Tool Design: What Works and What Doesn't." Jun 2026. https://machinelearningmastery.com/ai-agent-tool-design-what-works-and-what-doesnt/
- Shopify Engineering. "Building Production-Ready Agentic Systems." Aug 2025. https://shopify.engineering/building-production-ready-agentic-systems
- Srinivasan, V. "Bridging Protocol and Production: Design Patterns for Deploying AI Agents with Model Context Protocol." arXiv, Mar 2026. https://arxiv.org/pdf/2603.13417
- TreeRouter. "MCP Server Production Guide: 8 Critical Pitfalls & Fixes." May 2026. https://api.treerouter.ai/en/blog/mcp-server-production-pitfalls-fixes-guide
- Anthropic. "Building Effective AI Agents." Dec 2024. https://www.anthropic.com/engineering/building-effective-agents
- Pontil. "MCP servers: a practical setup and architecture guide." May 2026. https://www.pontil.com/blog/mcp-servers-a-practical-setup-and-architecture-guide
- Kerkhoff, M. "MCP Integration Development Guide 2026." Context Studios, Jul 2026. https://www.contextstudios.ai/guides/mcp-integration-development-guide-2026