Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

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.

How it works

The client lists a server's tools, the model picks one, you allow it, and tools/call runs the tool and brings the result back.language modelMCP clientin the host appyouMCP serverthe toolget_weather, publish1. tools/list2. names and schemas3. offers the tools4. picks one, arguments5. asks you to allow6. tools/call7. result, or isErrorruns
  1. The server declares the tools capability. The client calls tools/list and gets each tool's name, description, inputSchema and any outputSchema and annotations.

  2. The host puts those descriptions in front of the model. The model decides when a tool fits and produces arguments that match the schema.

  3. The client shows you the call where the host requires approval, then sends tools/call with the name and arguments.

  4. The server validates the input, does the work and returns content: text, images, audio, resource links, or structuredContent matching the outputSchema.

  5. 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: true and 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.