Why it matters
An MCP server can expose almost anything. The interesting design question is not what to expose but who decides when it is used. A model that can autonomously run a query needs a different contract from a document that the application chooses to attach, and both differ from a procedure a person explicitly starts.
MCP answers that with three server primitives, each with a different controller. Confusing them produces the two most common integration mistakes: wrapping every piece of data in a tool so the model burns turns fetching what the host could have attached, and wrapping every action in a resource so nothing can actually happen.
Mental model
A staffed library. Tools are the service desk: you ask for something to be done, and a person does it. Resources are the shelves: the librarian can fetch a specific item, and it is read-only. Prompts are the laminated guides by the entrance: a person picks one up and follows it.
The analogy breaks on selection. A library's catalogue is finite and stable; MCP lists are dynamic, paginated, and can be infinite in principle because resource templates are parameterised — weather://forecast/{city}/{date} describes a family of resources, not one shelf. And unlike a library, the "person" choosing a tool is a language model reading descriptions, so the description is part of the interface.
The three server primitives
| Primitive | Controller | Methods | Typical use |
|---|---|---|---|
| Tools | Model | tools/list, tools/call | Search, write, send, deploy |
| Resources | Application | resources/list, resources/templates/list, resources/read | Files, schemas, records, API responses |
| Prompts | User | prompts/list, prompts/get | Slash commands, workflows, few-shot templates |
completion/complete is a server utility, not a resource method: it suggests argument values for resource templates and prompt arguments. Keep it out of the resource row; it is available to both primitives.
Tools are executable functions. Each has a name, a human-readable title, a description, a JSON Schema inputSchema, and an optional outputSchema. A call returns a content array — text, image, audio, resource links, embedded resources — plus optional structuredContent that conforms to the output schema. Tools are how an agent changes something.
Resources are identified by URI and declare a MIME type. Direct resources are fixed; resource templates are parameterised, and completion/complete can suggest valid argument values. Reading one returns its contents plus caching hints (ttlMs, cacheScope). Resources are how data gets into context without the model asking for it.
Prompts are named templates with arguments. prompts/get returns messages that the application adds to the conversation. Prompt arguments are strings, so the description carries the format contract. Prompts are how a product ships a workflow — "review this PR", "plan a trip" — that a user chooses deliberately.
How it works
One envelope, three primitives. tools/list is host-started, tools/call is model-started, resources are application-driven and prompts are user-driven. Grey dotted rows are in-process hops; every wire request carries _meta, and every 2026-07-28 result carries resultType.
Host
model · app · user
Client
1 link
Server
declared primitives
{ "jsonrpc": "2.0", "id": 1,
"result": {
"resultType": "complete",
"tools": [{
"name": "issues_search",
"title": "Search issues",
"description": "Find issues by query. ...",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" } },
"required": ["query"] } }],
"ttlMs": 300000,
"cacheScope": "public" } }Step 1: tools/list. Hover, tap or tab to any message to inspect its payload.
Figure. All three exchanges use the same JSON-RPC envelope, and the methods encode who starts them: tools/call is model-started, tools/list is host-started, resources/read is application-driven, and prompts/get is user-driven. The result shapes differ for the same reason — a tool returns content the model reads, a resource returns bytes with cache hints, a prompt returns messages the application inserts.
What to notice. The failure is control confusion. Wrapping attachable data as a tool makes the model spend turns fetching what the host could have loaded; treating resources as something the model browses gives it a loop the host never authorised; and treating prompts/get as a system prompt lets a user-selected template outrank the host's policy.
Text version
Sequence across Host (model, application and user), Client and Server, with A2A-free MCP 2026-07-28 payloads. Step 1, tools/list: an in-process Host to Client registry refresh; Client to Server tools/list with _meta carrying protocolVersion and clientCapabilities; Server to Client resultType complete, a tools array whose issues_search inputSchema defines the query property, ttlMs 300000 and cacheScope public, with no nextCursor. Step 2, tools/call: an in-process Host to Client model tool call; Client to Server tools/call with name, arguments and _meta; Server to Client resultType complete, a content array, structuredContent matches 1, and isError false. Step 3, resources/read: an in-process Host to Client application selection; Client to Server resources/read with uri docs://policy/refunds and _meta; Server to Client resultType complete, a contents array with mimeType text/markdown, ttlMs 60000 and cacheScope private. Step 4, prompts/get: an in-process Host to Client user selection; Client to Server prompts/get with name review-pr and arguments; Server to Client resultType complete, a description and a messages array with role user and text content. The controller differs per primitive; the grey dotted rows are in-process hops, not wire messages.
- Capability declaration. The server's discovery response lists which primitives it supports and whether it can notify about changes (
listChanged,subscribe). - Listing. The client calls the list methods the capabilities allow. List results are paginated by cursor and carry cache hints, so a host can avoid re-listing on every turn.
- Selection. For tools, the host filters by policy and passes descriptors to the model. For resources, the host or user picks. For prompts, the user invokes by name.
- Invocation.
tools/callwithnameandarguments, orresources/readwith auri, orprompts/getwithnameandarguments. - Result handling. The host validates structured output where present, decides how much of the content enters context, and records the call.
- Change notification. If the client subscribed,
notifications/tools/list_changedor a resource update prompts a refresh.
A tool descriptor is small, and every field in it is read by a model:
{
"name": "issues_search",
"title": "Search issues",
"description": "Find issues by free-text query. Returns at most 20 matches with id, title and state. Use issues_get for full text.",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "Words from the title or body" },
"state": { "type": "string", "enum": ["open", "closed", "any"], "default": "open" }
},
"required": ["query"]
},
"outputSchema": {
"type": "object",
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": { "id": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" } },
"required": ["id", "title", "state"]
}
}
},
"required": ["matches"]
}
}Client-side primitives
Servers are not the only side with something to offer. Elicitation lets a server ask the user for information mid-request: it returns an InputRequiredResult carrying elicitation/create requests, and the client retries with inputResponses and the echoed requestState.
Elicitation comes in two modes. Form mode collects structured data against a schema. URL mode hands the user a URL and keeps the interaction out of band — the right mode for credentials, payments and third-party authorisation, which must never pass through the model's context.
Two older client primitives are now deprecated. Roots (telling a server which directories it may touch) is replaced by passing paths as tool arguments or configuration; sampling (asking the client to run a completion) is replaced by calling a provider API directly. New servers should not build on either.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Action as a tool | Anything the model must decide to do | Prompt tokens per tool, selection error | The action is read-only data the host could attach |
| Data as a resource | Large, browsable, read-only context | Host must choose what to load | The model needs to search or filter it |
| Workflow as a prompt | Repeatable, user-initiated procedures | Not discoverable by the model | The trigger should be automatic |
| One mega-tool with a mode argument | Very large API surfaces | Schema complexity, wrong mode selection | The modes have different permissions |
Good for
Anything the model must decide to do
Cost
Prompt tokens per tool, selection error
Fails when
The action is read-only data the host could attach
- The action is read-only data the host could attach
- The model needs to search or filter it
- The trigger should be automatic
- The modes have different permissions
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Action as a tool is good for Anything the model must decide to do, costs Prompt tokens per tool, selection error, and fails when The action is read-only data the host could attach. Data as a resource is good for Large, browsable, read-only context, costs Host must choose what to load, and fails when The model needs to search or filter it. Workflow as a prompt is good for Repeatable, user-initiated procedures, costs Not discoverable by the model, and fails when The trigger should be automatic. One mega-tool with a mode argument is good for Very large API surfaces, costs Schema complexity, wrong mode selection, and fails when The modes have different permissions
Failure modes
- Ambiguous tool descriptions. Two tools overlap, and the model alternates between them. Debug: replaying a fixed set of user requests and logging which tool was chosen; rewrite descriptions to state when not to use the tool.
- Resources dumped wholesale. The host reads every listed resource into the prompt and blows the budget. Debug: measuring tokens contributed per resource and by switching to templates plus completion-driven selection.
- Prompt templates that rot. A prompt embeds instructions that no longer match the tools it references. Debug: rendering the prompt and asserting that every tool it names exists in the current
tools/list. - Mega-tools with mixed permissions. One tool covers read and write, so the host cannot approve one without approving the other. Debug: inspecting the call log for privileged operations that were approved under a read-only consent.
In production
Tool descriptors are a permanent context tax: they are sent on every request unless the host prunes or discloses them progressively. Track tokens spent on tool definitions separately from conversation tokens, and cap the number of tools visible per turn.
Resources need a cache policy, not just a read. Honour ttlMs, respect cacheScope so a private resource is never served from a shared cache, and invalidate on notifications/resources/updated when subscribed.
For prompts, version them with the server. A prompt is product surface: changing its text changes behaviour for every host that invokes it, without any client deploy.
Common misconceptions
People think: Resources are for the model to browse.
Actually: Resources are application-controlled. The host or user selects them; the model does not get a browsing loop unless the host builds one on top.
People think: You should expose your whole REST API as tools.
Actually: A one-to-one mapping produces many narrow tools and heavy prompts. Group by task, return compact results, and keep the number of choices a model faces small.
People think: Prompts are system prompts.
Actually: A prompt is a user-invoked template that returns messages the application inserts. System-level behaviour remains the host's responsibility.
Interview angle
"The model keeps calling the wrong tool — what do you do?" is a primitives question in disguise. A good answer inspects the descriptors the model actually saw, checks for overlap and missing negative guidance, considers whether the data should have been a resource instead of a tool, then measures selection accuracy on a fixed set before and after the rewrite. Mention that annotations are advisory, and that the host owns approval. See tool schemas and the protocols interview category.
Sources
- MCP server concepts — tools, resources, prompts and their controllers.
- MCP client concepts — elicitation modes, privacy rules and deprecations.
- MCP architecture overview — primitives, discovery and notifications.
- MCP specification, revision 2026-07-28 — normative method and result shapes.
Related
- MCP — the protocol these primitives belong to.
- Host/client/server — which role controls what.
- Authorisation and security — scoping access to privileged tools.
- Tool schemas — schema and description design.
- Context engineering — deciding what enters the window.