MCP Tools: The Complete Guide to the Primitive and the Ecosystem

What "MCP tools" actually means

Search for MCP tools and you get two different articles wearing the same title. One is about tools as defined in the Model Context Protocol specification, a formal primitive sitting next to resources and prompts. The other is a list of MCP servers you can install. Both are legitimate uses of the phrase, and most people arrive wanting a bit of each: they read that an agent "has tools", they want to know what that means mechanically, and then they want to know which ones are worth connecting.

This guide covers both, protocol meaning first, because almost every practical question about the ecosystem, why an agent picked the wrong server, why adding the tenth integration made things worse, why a tool description is a security boundary, resolves back into how the primitive works.

If you are completely new to the protocol itself, our explainer on what MCP is covers the client/server architecture this guide assumes.

The three MCP primitives: tools, resources, and prompts

An MCP server can offer three kinds of thing, and the spec's own server overview separates them by a single question: who decides when this gets used?

Tools are the model-controlled one

The specification is explicit that tools are "model-controlled, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts." That autonomy is the whole point, and it is also the source of every risk further down this page. The same section says there "SHOULD always be a human in the loop with the ability to deny tool invocations", and asks applications to show which tools are exposed, indicate visually when one is invoked, and prompt for confirmation on operations.

Resources are pulled in by the application, not chosen by the model

Resources are identified by URI and are, in the spec's words, "application-driven, with host applications determining how to incorporate context based on their needs." A host might show resources in a tree for the user to pick, let the user search them, or include them automatically by heuristic. The distinction from tools is not about what the data is; it is about who is holding the steering wheel. A file exposed as a resource is something your app decided to show the model. The same file behind a `read_file` tool is something the model decides to go get.

Prompts are triggered by the user

Prompts are "user-controlled", exposed so the user can explicitly select them, typically surfaced as slash commands. The spec adds a clarification worth repeating because people get it backwards: user-controlled "refers to who decides when the prompt is used, not who authors its content." The server still writes the prompt.

Why the split matters when you are building

Most server authors implement tools and stop. That is usually fine, but it means everything becomes model-controlled, including things the user should be picking and context the application should be deciding on. If a capability only makes sense when a person deliberately invokes it, it is a prompt. If it is reference material your app knows is relevant, it is a resource, and turning it into a tool just adds one more definition competing for the model's attention. The practical cost of collapsing all three into tools shows up later as tool sprawl.

The anatomy of an MCP tool definition

Here is what a server actually returns for one tool, taken from the specification's own example:

Names

Tool names SHOULD be 1 to 128 characters, are case-sensitive, and SHOULD use only ASCII letters, digits, underscore, hyphen and dot. No spaces or commas. Uniqueness is scoped to a single server, which matters the moment a client connects to several servers at once: two servers can both ship a tool called `search`, and resolving that collision is the client's problem, not the protocol's. This is the mechanical reason namespacing exists.

Descriptions

The description does more work than any other field in the definition, and it is the one most server authors treat as an afterthought. It is not documentation for a human reading your README. It is text loaded directly into the model's context, where it functions as an instruction. Anthropic's engineering post Writing effective tools for agents (11 September 2025) puts the standard plainly: write the description the way you would explain the tool "to a new hire on your team", making explicit the context you would otherwise bring implicitly, specialised query formats, niche terminology, how the underlying resources relate to each other.

The same post notes that small refinements here move real numbers. Claude Sonnet 3.5 reached state-of-the-art on SWE-bench Verified after what Anthropic describes as precise refinements to tool descriptions that dramatically reduced error rates. Nothing about the underlying tools changed. The text describing them did.

Input schema

`inputSchema` MUST be a valid JSON Schema object, not null, and defaults to the 2020-12 dialect when no `$schema` field is present. For a tool with no parameters the spec recommends `{ "type": "object", "additionalProperties": false }` rather than an empty or absent schema.

Parameter naming is worth as much care as the description. Anthropic's guidance is specific: "instead of a parameter named `user`, try a parameter named `user_id`". Ambiguity in a parameter name becomes a wrong argument at runtime, and the model has nothing else to go on.

Output schema and structured content

A tool MAY declare an `outputSchema`. If it does, servers MUST return structured results conforming to it in the `structuredContent` field, and clients SHOULD validate against it. For backwards compatibility a tool returning structured content SHOULD also serialise the JSON into a text block. The spec adds a clarifying note that trips people up: `structuredContent` is server-produced result data and is unrelated to LLM "structured outputs" in the schema-constrained-generation sense.

Annotations, which are untrusted by design

Annotations describe tool behaviour, for example hinting that a tool is read-only or destructive. The specification's position on them is blunt and worth quoting for anyone building a client: "clients MUST consider tool annotations to be untrusted unless they come from trusted servers." An annotation is a claim made by the server about itself. A malicious server will happily claim to be read-only. Treating annotations as a security control is a category error; they are a UI affordance.

How tool discovery and invocation work at runtime

Discovery

The client sends `tools/list` and gets back an array of tool definitions. The operation supports pagination via a cursor and caching via `ttlMs` and `cacheScope`. Two requirements in the 2026-07-28 revision are easy to miss and both exist for performance reasons:

The tool set MUST NOT vary per-connection or as a side effect of other requests, though it MAY vary by the authorization presented on the request, for example returning only the tools the caller's granted scopes permit. And servers SHOULD return tools in a deterministic order, because stable ordering lets clients cache the list and, in the spec's words, "improves LLM prompt cache hit rates when tools are included in model context."

That last clause is the tell for where the real cost sits. Tool definitions are not metadata sitting off to the side. They are tokens in the prompt, on every turn.

Invocation

The client sends `tools/call` with a name and an arguments object. The server returns content blocks, which can be text, image, audio, resource links, or embedded resources, plus optional structured content. A server MAY also respond with an `input_required` result, which pauses the call to collect more input from the user through elicitation before the client retries with the responses attached.

Two kinds of error, and why the difference matters

The spec splits errors deliberately. Protocol errors, an unknown tool, a malformed request, a server fault, come back as standard JSON-RPC errors and are things "models are less likely to be able to fix". Tool execution errors come back inside a normal result with `isError: true`, and are meant to carry "actionable feedback that language models can use to self-correct and retry with adjusted parameters": a date in the wrong format, a value out of range, a business rule violation.

Clients SHOULD pass execution errors to the model so it can recover. This has a direct implication for server authors: a generic "request failed" string throws away the entire self-correction mechanism the protocol built for you. `Invalid departure date: must be in the future. Current date is 08/08/2025.` is a better error than a 500, not because it is politer, but because the model can act on it.

Change notifications

A server declaring `listChanged` SHOULD notify clients when its tool set changes, via `notifications/tools/list_changed`. Useful, and also the mechanism that makes rug-pull attacks possible, which we come back to below.

Why tool descriptions determine whether a model calls the tool correctly

Everything the model knows about your tool before it calls it comes from three strings and a schema: the name, the description, the parameter names, and the types. There is no documentation site it consults, no examples it looks up, no colleague it asks. Anthropic's framing is that tool descriptions and specs, because they are loaded into context, "collectively steer agents toward effective tool-calling behaviors."

Some concrete things that measurably help, from that same engineering post:

• Resolve cryptic identifiers into natural language. Anthropic found that converting arbitrary alphanumeric UUIDs into semantically meaningful values, or even a simple 0-indexed scheme, "significantly improves Claude's precision in retrieval tasks by reducing hallucinations."
• Return high-signal fields, not every field. Prefer `name`, `image_url`, `file_type` over `uuid`, `256px_image_url`, `mime_type`. Fields that inform the next action beat fields that are technically complete.
• Offer a response format control. Exposing a `response_format` enum with `concise` and `detailed` lets the agent choose. In Anthropic's Slack example the concise form used roughly a third of the tokens of the detailed one.
• Cap and paginate responses. Claude Code restricts tool responses to 25,000 tokens by default. If you truncate, say so in the response and tell the agent what to do instead, for example run a narrower search.
• Test with an agent, not by reading. Build an evaluation, run it, and collect more than top-line accuracy: runtime per tool call, number of tool calls, total token consumption, and tool errors. Anthropic notes that tracking which tools get called reveals workflows worth consolidating into a single tool.

That last point deserves emphasis because it inverts the usual instinct. If your evaluation shows the agent calling `list_users`, then `get_user`, then `get_user_activity` every single time, those three tools are one tool that you have not written yet.

Why too many MCP tools makes agents worse

This is the part most "best MCP tools" listicles skip, and it is the single most useful thing to know before you connect your fifth server.

The measured effect

The RAG-MCP paper (arXiv:2505.03275, May 2025) ran a stress test that varied the number of available MCP tools and measured selection accuracy directly. Their retrieval-based approach, which puts only semantically relevant tool descriptions in front of the model, scored 43.13% selection accuracy against a 13.62% baseline where everything was loaded into the prompt, while cutting prompt tokens by more than half. The authors describe the failure mode as prompt bloat: "the context window becomes saturated with distractors, reducing the model's capacity to distinguish and recall the correct tool."

Anthropic's own guidance says the same thing from the builder's side: "Too many tools or overlapping tools can also distract agents from pursuing efficient strategies."

The token cost is not small

Anthropic's Code execution with MCP (4 November 2025) quantifies the other half of the problem. Most MCP clients load every tool definition upfront, and every intermediate result passes back through the context window. For agents connected to very large tool sets, that means processing "hundreds of thousands of tokens before reading a request". Their worked example moves a workflow from 150,000 tokens to 2,000 by having the agent write code against an on-demand tool interface instead of loading everything, a 98.7% reduction.

What to actually do about it

Namespacing is the cheapest of these and the most underused. Anthropic notes that agents "potentially gain access to dozens of MCP servers and hundreds of different tools", and that when tools overlap or have vague purposes, agents get confused about which to use. Grouping by service (`asana_search`, `jira_search`) and by resource (`asana_projects_search`, `asana_users_search`) delineates the boundaries. Their caveat is honest and worth respecting: prefix versus suffix namespacing had non-trivial and model-dependent effects on their evaluations, so test rather than assume.

Tool design best practices for anyone building an MCP server

The stateful point is a newer addition to the spec and easy to miss. Where a tool returns a handle the model carries forward across calls, the specification asks servers to validate authorization against the handle on every call, keep handles opaque, bound their lifetime, and state the retention policy in the creating tool's description, for example "baskets expire after 24 hours of inactivity", so the model can see it when deciding to create state. Expired handles should return a tool execution error saying so, so the model can recover by making a new one.

The security dimension: what tool definitions let attackers do

This is well documented, it is not theoretical, and it follows directly from the design: a tool description is metadata to a developer and an instruction to a model.

Tool poisoning

Invariant Labs disclosed the attack class on 1 April 2025. Malicious instructions are embedded in a tool's description where they are invisible to the user in most UIs but fully visible to the model. Their proof of concept against a code editor put exfiltration directives inside a calculator server's description; invoking the add function caused the model to read the developer's SSH private key and MCP configuration file and send both to a remote endpoint, while the visible output was a correct arithmetic result. Invariant's own summary is that a malicious server "cannot only exfiltrate sensitive data from the user but also hijack the agent's behavior and override instructions provided by other, trusted servers."

The scale of the exposure was measured later. MCPTox (August 2025) built a benchmark on 45 live, real-world MCP servers and 353 authentic tools, generating 1,312 malicious test cases across 10 risk categories, and evaluated 20 LLM agents. Attack success rates reached 72.8% for o1-mini, and the paper reports that more capable models were often more susceptible, because the attack exploits their superior instruction-following. The refusal numbers are the alarming part: the highest refusal rate of any model tested, Claude 3.7 Sonnet, was under 3%. Safety alignment does not catch this, because every individual action the agent takes is a legitimate use of a legitimate tool.

Rug pulls

A tool you approved is not a tool that stays the same. Because servers can change definitions and notify clients of the change, a server can present a benign tool during review and alter its description or behaviour afterwards. Whether that triggers re-approval depends entirely on the client. The ETDI paper (June 2025) characterises the gap precisely: if the tool's identifier is superficially unchanged, or the client is not designed to detect modifications in the schema or descriptive metadata, no new approval prompt fires. Their proposed mitigation is immutable versioning, where any change to permissions or schema forces a new version and therefore re-approval.

Confused deputy

The MCP project's own security best practices documents this one against MCP proxy servers fronting third-party APIs. The vulnerable configuration is specific: the proxy uses a static client ID with the third-party authorization server, it allows MCP clients to dynamically register, and the third-party server sets a consent cookie after the first authorization. An attacker can then obtain an authorization code without the user consenting again, by supplying a malicious `redirect_uri` during dynamic registration, and exchange it for an access token. The deputy, your proxy, is confused into using its own legitimate authority on an attacker's behalf.

The lethal trifecta

Simon Willison's framing from 16 June 2025 is the most useful mental model for auditing a tool set, because it does not require identifying a malicious server at all. Three capabilities in combination are sufficient for data theft: access to private data, exposure to untrusted content, and the ability to communicate externally. Any agent holding all three can be talked into stealing from its own user.

Invariant's GitHub MCP writeup (26 May 2025) is the canonical worked example, and notably involves no malicious server whatsoever. The official GitHub MCP server, a public repo anyone can file issues on, a private repo, and a benign user prompt like "have a look at the open issues". The agent reads a poisoned issue, pulls private repository data into context, and leaks it in an autonomously created pull request on the public repo. Every component behaved as designed. The corresponding issue on the GitHub MCP repository records independent reproduction with both OAuth and personal access tokens, and makes the general point: this is true of any tool combination that completes the trifecta, and worse when the agent can also run shell commands.

The attack surface, summarised

Note the last row. Poisoned descriptions get the headlines, but the GitHub case shows the payload arriving in the output of a completely legitimate tool. Reviewing your servers' descriptions is necessary and nowhere near sufficient. Our deeper treatment of MCP security covers the controls side, and what changes at enterprise scale covers the governance side.

The controls the spec actually asks for

Servers MUST validate all tool inputs, implement access controls, rate limit invocations, and sanitise outputs. Clients SHOULD prompt for confirmation on sensitive operations, show tool inputs to the user before the call to prevent accidental or malicious exfiltration, validate results before passing them to the model, implement timeouts, and log tool usage for audit. Most of the documented incidents involve at least one of these being absent.

MCP tools versus traditional function calling

People often ask whether MCP tools are just function calling with extra steps. Not quite, and the difference is about who owns the tool list.

Function calling is the model capability: the model emits a structured request to invoke something. MCP does not replace that. It standardises where the tool definitions come from and how the invocation travels, so a tool written once is usable by Claude Code, Cursor, ChatGPT or anything else that speaks the protocol. Your runtime still surfaces MCP tools to the model through ordinary function calling.

The trade you make is the last row. A function in your codebase was reviewed by your team. A tool from an MCP server crosses a trust boundary, which is precisely why the security section above exists. Our MCP vs API comparison works through the integration-design consequences.

The practical ecosystem: which MCP tools people actually use

Now the colloquial meaning. The ecosystem is large and uneven. The official MCP Registry launched in preview on 8 September 2025 as an open catalogue and API, backed by Anthropic, GitHub, Microsoft and PulseMCP, and explicitly does not list private servers. Third-party directories are larger: PulseMCP's directory listed 21,870 servers when I checked it on 18 September 2026.

That number is a reason for scepticism, not enthusiasm. Most of those servers are one person's weekend project with a single contributor and no security review. The categories below are what teams actually connect, based on the servers that consistently trend across directories.

Two patterns are worth naming. First, categories are not equally mature; official vendor-maintained servers are usually a different class of artifact from a community wrapper with the same name. Second, connecting more of these categories is what puts the trifecta together, because private data, untrusted content and external communication tend to arrive in different servers that nobody evaluated as a set.

If you are picking, our framework for choosing MCP servers covers the evaluation criteria, and our guide to MCP servers for Claude Code covers the developer-workflow end specifically.

Where a unified layer changes the calculation

The through-line from the protocol half of this guide to the ecosystem half is this: every server you add spends context, adds a trust boundary, and makes tool selection harder. Ten servers is ten sets of definitions in every prompt, ten auth flows, ten maintainers, and no shared understanding between any of them. Ask a question that spans two systems, whether what you told a customer in Slack matches what is recorded in Salesforce, and a pile of single-purpose servers cannot answer it, because each one only knows its own data.

Coworker MCP is built the other way round: one connection giving any MCP-compatible client access to 50+ connected apps, Slack, Jira, Salesforce, GitHub and Google Drive among them, searchable as one system rather than ten. One governance point instead of ten, one set of tools to evaluate instead of ten, and cross-system questions that individual servers structurally cannot answer. SOC 2 Type II and GDPR compliant.

See how Coworker MCP works, or book a demo to walk through your current server list.

Frequently asked questions

What are MCP tools?

In the Model Context Protocol, a tool is an executable function an MCP server exposes to a model, with a name, a description, and a JSON Schema for its inputs. The model discovers available tools with `tools/list` and invokes them with `tools/call`. Colloquially, "MCP tools" is also used to mean the wider ecosystem of MCP servers you can connect to an AI client. Both meanings are common.

What is the difference between MCP tools, resources, and prompts?

Control. Tools are model-controlled: the model decides when to invoke them. Resources are application-driven: the host app decides what context to include. Prompts are user-controlled: the user explicitly selects them, typically as slash commands. All three are server features defined in the specification, and the choice between them is about who is deciding, not about what the data is.

How does a model know which MCP tool to call?

From the tool definition alone: the name, the description, the parameter names, and the schema types. There is no other source of information at call time. That is why description quality is the dominant factor in whether a tool gets called correctly, and why ambiguous parameter names produce wrong arguments.

Can you have too many MCP tools?

Yes, and it is measurable. The RAG-MCP stress test found tool-selection accuracy of 13.62% when all tool descriptions were loaded into the prompt, against 43.13% when only semantically relevant ones were retrieved. Anthropic's guidance likewise warns that too many or overlapping tools distract agents from efficient strategies. Practical mitigations are disabling unused servers, namespacing, scoping tool sets per task, and retrieval or code execution for large pools.

Are MCP tools the same as function calling?

No, though they work together. Function calling is the model capability of emitting a structured request to invoke something. MCP standardises where tool definitions come from and how invocations travel, so one server works with any compatible client rather than being rewritten per provider. Your runtime still presents MCP tools to the model through function calling.

What is tool poisoning in MCP?

Embedding malicious instructions inside a tool's description, where users rarely see them but the model always does. Invariant Labs disclosed it on 1 April 2025 with a working proof of concept that exfiltrated SSH keys while showing the user a correct result. The MCPTox benchmark later measured attack success rates up to 72.8% across 20 agents, with the best-performing model refusing under 3% of attempts.

How do I secure MCP tools?

Start by breaking the lethal trifecta: do not give one agent private data access, exposure to untrusted content, and external communication at the same time. Then apply the spec's own asks: validate inputs, scope credentials, rate limit, show tool inputs to the user before the call, require confirmation on sensitive operations, and log invocations. Treat tool annotations as untrusted claims, not controls, and pin or re-review server versions so a definition cannot change silently after approval.

Do MCP tool definitions cost tokens?

Yes, on every turn. Most clients load all definitions upfront into context. Anthropic reports that agents connected to very large tool sets can process hundreds of thousands of tokens before reading the request, and shows a workflow going from 150,000 tokens to 2,000 by loading definitions on demand instead. This is the main reason connecting servers you do not use is not free.

What is the difference between an MCP tool and an MCP server?

A server is the process that exposes capabilities; a tool is one capability it exposes. A single server typically offers many tools, and may also offer resources and prompts. A client connects to servers, not to individual tools.

Related reading

• What Is MCP? A Complete Guide
• MCP vs API: What Changes When You Standardise the Connection
• MCP Security: The Risks, and What Actually Mitigates Them
• How to Choose MCP Servers for Your Team
• Enterprise MCP: Governance at Scale
• MCP Servers for Claude Code