Map · Agents · 03 · Tool design/MCP
Concept card · Agents
Tool design is how a tool is named, described, and exposed, including over the Model Context Protocol (MCP).
How a tool is named, described, and exposed, including over MCP.
Oct 18: First card. The picture switches one tool between a vague description and a specific one. MCP is a section of this card, matching the registry. Sources are the MCP introduction, the MCP tools specification, Anthropic's define-tools guide, and OpenAI's function calling guide.
Tool design is the name, the description, and the input schema you give a tool before a model can ask for it. OpenAI's function calling guide says the description is details on when and how to use the function, and lists clear names and parameter descriptions as the first practice. Anthropic's define-tools guide says a tool definition includes a name, a plaintext description of what the tool does, when it should be used, and how it behaves, and a JSON schema for the parameters. The same guide says a detailed description is by far the most important factor in tool performance, and to aim for at least three or four sentences. The Model Context Protocol is one way to expose that tool: a name, a description, and an input schema, listed below.
The Model Context Protocol (MCP) is one way to expose that same tool. The MCP introduction describes MCP as an open-source standard for connecting AI applications to external systems, including tools such as search engines and calculators. The MCP tools specification says each tool is identified by a name and includes a human-readable description and an input schema, which must be a JSON schema object. A client lists tools, the model selects one, and the client sends a tools/call request to the server. The specification says there should be a human in the loop who can deny a tool invocation, and that clients must treat tool annotations as untrusted unless they come from a trusted server.
The definition rides along in the request. OpenAI's function calling guide says callable function definitions count against the model's context limit and are billed as input tokens. A longer description uses more input tokens. This card does not add a price.
The model picks a tool from the name and the description. Anthropic's guide says the description should cover what the tool does, when to use it, when not to, and what each parameter means. OpenAI's guide says to keep the number of functions available at the start of a turn small, and calls fewer than 20 a soft suggestion.
A tool the model can name is a tool your code may run. The MCP tools specification says servers must validate tool inputs, and that clients should prompt before a sensitive call. Annotations on a tool are hints. The specification says not to trust them from a server you do not trust.
Take one function you already expose. Write the name, when to call it, when not to, and what each parameter means. If you expose it over MCP, check that the tool has a name, a description, and an input schema.
A name like do_thing and a description that only says what it does, not when to use it. Anthropic's guide says the description is how the model decides when and how to call the tool.
A tool is named do_thing. The description is "Does the thing." What is missing?
Coming soon. One tool you already expose, rewritten so the description says when to call it and when not to.
Coming soon. How an MCP tool definition lines up with an OpenAI or Anthropic function schema.