What are MCP tools?
MCP tools are functions an MCP server exposes for a language model to call. Each tool has a name, a description and a JSON Schema for its arguments. The client lists them with tools/list, the model picks one, and tools/call runs it and returns content. Tools are the way an agent acts, not just reads.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
The server declares the tools capability. The client calls tools/list and gets each tool's name, description, inputSchema and any outputSchema and annotations.
The host puts those descriptions in front of the model. The model decides when a tool fits and produces arguments that match the schema.
The client shows you the call where the host requires approval, then sends tools/call with the name and arguments.
The server validates the input, does the work and returns content: text, images, audio, resource links, or structuredContent matching the outputSchema.
A bad request is a JSON-RPC error. A failure the model can fix comes back as a normal result with isError true, so the model reads it and retries.
Source: MCP specification: tools
MCP tools versus resources and prompts
A server can expose three kinds of thing, and the specification sorts them by who is in control. Tools are model-controlled: the model discovers and invokes them on its own judgement. Resources are application-controlled: the host decides which file contents or records to attach as context. Prompts are user-controlled: a person picks one, like a slash command. If you find yourself writing a tool called get_readme that takes no arguments and returns a file, it probably wants to be a resource. If the "tool" is really a canned instruction for the model, it is a prompt. Tools are for actions and lookups the model should decide to make.
Example: a tool definition
{
"name": "get_weather",
"title": "Weather Information Provider",
"description": "Get current weather information for a location",
"inputSchema": {
"type": "object",
"properties": {
"location": { "type": "string", "description": "City name or zip code" }
},
"required": ["location"]
}
}
The model never sees your code. It sees this. The description and the property descriptions are the whole interface, so write them for a reader who has to decide, in one pass, whether this tool answers the question. The schema defaults to JSON Schema 2020-12. A tool with no parameters should still carry { "type": "object", "additionalProperties": false }; a null schema is invalid. Names should be 1 to 128 characters of letters, digits, underscores, hyphens and dots, and unique within the server.
On the Intraface server, pull_board returns a board's files but caps the inline text at 40 KB and lists the rest for read_file to fetch in pages. That cap is a tool-design choice: a result the model cannot fit in its context is a wasted call.
When to use a tool
Use a tool whenever the model needs to do something or fetch something it chooses at run time: query a database, open a ticket, publish a page. Keep the set small and the names plain. Return the list from tools/list in a deterministic order, which the spec recommends because clients cache it and a stable order improves prompt cache hits. If a tool needs to carry state across calls, such as an open cart or a browser session, return an explicit handle in the result and accept it as an argument next time; the protocol has no session for you to lean on.
Common mistakes
- Returning failures as JSON-RPC errors. An unknown tool or malformed request is a protocol error. A wrong date format or a failed API call should be a result with
isError: trueand a readable message; the spec says clients should pass those to the model so it can self-correct. - Trusting annotations. Annotations describe a tool's behaviour, but they come from the server. Clients must treat them as untrusted unless the server is trusted, so do not expect them to skip an approval prompt.
- Putting secrets in the definition. Everything in a tool definition goes into the model's context and often into logs, and tool inputs are meant to be shown to the user before the call. Design for that.
FAQ
- How are MCP tools different from function calling?
- Function calling is a model feature: the model emits a structured call to a function the app described. MCP tools are a protocol feature: a standard way for a server to publish such functions so any host can offer them to its model. A host presents MCP tools to its model the same way it presents its own functions.
- Do MCP tools run automatically?
- The model can choose them on its own, which is what model-controlled means, but the specification says there should always be a human able to deny a tool invocation and that clients should confirm sensitive operations. Whether a given call needs a click is the host's setting.
- What happens when an MCP tool fails?
- Two cases. A protocol problem, such as an unknown tool name, comes back as a JSON-RPC error. A failure the model can act on, such as an invalid argument or an upstream API error, comes back as a normal result with isError set to true and a message explaining what went wrong.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.