In the latest installment of the AI System Design series, Internals Decoded dissects the mechanics of tool calling and the Model Context Protocol (MCP) using 'Mailmind,' a fictional AI email assistant. The core thesis is counterintuitive for traditional software engineers: the most critical component of a tool is not its code, but its natural-language description. An LLM agent cannot inspect the implementation; it reasons entirely from the prompt and the history of observations. If the description is vague, the agent hallucinates capabilities, leading to catastrophic context window pollution and failed workflows.

The ReAct Loop and Description Precision

Agents operate on a thought-action-observation cycle, where actions are structured function calls. The source material highlights that a tool's anatomy consists of a name, input schema, and description. The description serves as the agent's only interface to the tool’s semantics. For Mailmind, a poor description like 'Gets email information' causes the agent to misuse the tool for searching or deleting. A precise description explicitly states when to use the tool, what it returns, and crucially, when NOT to use it. This precision prevents the agent from inventing non-existent features, ensuring it calls search_inbox for threads and get_email_info for specific IDs.

Handling Failure and Context Bloat

Reliability in agent systems depends on graceful degradation. The article categorizes failures into transient (retried with exponential backoff), permanent (no retry, agent reasons alternatives), and dead services (circuit breaker opens). Without these mechanisms, a single 500 error can poison the context window. Furthermore, tool output must be strictly optimized. Returning full email bodies for 200 results can consume 25,000 tokens, wiping out reasoning capabilities. The solution involves pagination, caching, and returning only essential fields like IDs and snippets, reducing token usage to roughly 800 tokens for the same dataset.

The Outbox Pattern for Multi-System Consistency

When an agent interacts with multiple external systemsβ€”such as archiving an email and updating a task listβ€”silent partial failures create inconsistent states. The source rejects rolling back completed updates in separate systems, which creates a mess of compensating transactions. Instead, it advocates for the outbox pattern. The agent writes intended actions to a local outbox table synchronously. A background worker then executes these actions against external APIs, retrying independently. If an action fails after all retries, it moves to a dead-letter queue, triggering alerts. This turns multi-system operations into atomic writes from the agent's perspective, ensuring eventual consistency.

MCP as the USB-C for AI Tools

Before MCP, every agent integration required custom glue code for discovery, authentication, and transport. MCP standardizes this by defining a protocol where agents act as clients connecting to tool servers. The server advertises capabilities and tools via JSON schemas, allowing any MCP client to use any MCP server. This decouples the agent logic from the implementation details. The protocol is transport-agnostic, supporting stdio, HTTP with Server-Sent Events, and WebSockets. For Mailmind, this means the agent sees a unified toolset from Gmail, Calendar, and Task managers without custom integration code for each.

Key Takeaways

  • Tool descriptions are the primary driver of agent behavior; treat them as high-leverage configuration, not documentation.
  • Never return raw, large datasets to the agent; use pagination and field filtering to preserve context window budget.
  • Implement the outbox pattern for any multi-system write to avoid inconsistent states during partial failures.
  • MCP standardizes tool discovery and transport, eliminating brittle custom glue code for every new integration.
  • Circuit breakers and structured error observations are mandatory for preventing transient network issues from derailing conversations.

The Bottom Line

Stop treating tool descriptions as afterthoughts. They are the actual API contract for your agent's brain; if you don't define the boundaries in natural language, the model will invent its own.