Tool design and MCP basics

A team gives their new agent 38 tools, one for every endpoint in their REST API. It looks thorough. In practice the agent calls get_user, then list_orders, then get_order five times, then get_order_items five more times, to answer "what did I order last week?". It sometimes picks get_order_v2 instead of get_order. Each call is a full model round trip.

An API designed for programs is the wrong shape for a model. This chapter is about designing tools a model can use well, and about MCP, the standard way to plug those tools into any AI application.

Design for the task, not the endpoint#

A program calls an API cheaply and precisely, thousands of times a second. A model calls a tool slowly, expensively, and by reading a description. That changes what a good interface looks like.

Consolidate. One tool that answers a whole question beats four that each fetch a piece. get_recent_orders(days) that returns orders with their items and delivery status replaces three endpoints and five round trips.

Name and describe for a reader. The description is a prompt. Say what the tool does, when to use it, and when not to. "Search past orders by item name or date. Use when the customer refers to an order without an id. Do not use for orders still in progress, use get_live_order instead."

Make arguments hard to get wrong. Enums instead of free strings. Human readable ids where you can, since models copy long UUIDs badly. Sensible defaults so most calls need one or two arguments.

Return what the model needs, briefly. Fields a person would read, not internal columns. If results are truncated, say so and say how to get more: "Showing 10 of 63 orders. Pass page=2 for more."

Make errors useful. "Error 404" teaches nothing. "No order 44812 for this customer. Their recent orders are 44821 and 44790." lets the model fix its own mistake on the next step.

{
  "name": "get_recent_orders",
  "description": "List this customer's orders from the last N days, newest first, with items and delivery status. Use when the customer asks about past orders. For an order still on its way, use get_live_order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 },
      "status": { "enum": ["any", "delivered", "cancelled", "refunded"], "default": "any" }
    }
  }
}

Notice what is missing: there is no customer_id argument. The tool reads the logged in customer from the session in your code. An argument the model never supplies is an argument nobody can trick it into supplying wrongly.

How many tools?#

Every tool definition is sent on every call, so 40 tools can cost thousands of tokens before the user has typed anything, and a long menu makes the model pick wrong more often. Keep the set small and distinct. If two tools are easy to confuse, merge them or rename them until a new teammate could tell them apart from the names alone. When you genuinely need many, group them with prefixes (orders_search, orders_refund) or load groups only when a step needs them.

MCP: one plug for every tool#

Before 2024, every AI application wired up every tool by hand. Ten apps and twenty tools meant up to two hundred custom integrations. The Model Context Protocol, an open standard Anthropic introduced in November 2024, now governed by the Linux Foundation's Agentic AI Foundation and supported across AI tools and editors, turns that into a plug and socket. A tool is written once as an MCP server, and any application that speaks MCP can use it.

An MCP server can offer three kinds of thing. Tools the model can call, like get_recent_orders. Resources, read only data the application can load into context, like a file or a database schema. And prompts, reusable templates a user can pick. Messages are JSON-RPC, and a server runs either locally as a process the host starts (talking over standard input and output) or remotely over HTTP. Since the 2026-07-28 revision the protocol is stateless: there is no session or handshake, and every request carries its own protocol version. The MCP section goes deep on all of this.

Here is what happens when a host connects to a server and the model uses one of its tools.

Checkpoint#