How do I decide whether something should be a tool or a resource?

Ask whether the model is requesting an operation or reading context. If invocation performs work, changes state, calls another system, or can fail like an action, use a tool. If the capability is mainly something to inspect, quote, compare, or include in context, model it as a resource.

What is the difference between a prompt and a tool description?

A tool description tells the model when and how to call one operation. A prompt is a reusable task frame, such as a review, migration, or triage workflow. It can combine instructions, parameters, expected output shape, and references to resources or tools without pretending to be an executable action itself.

Why is making everything a tool a bad design?

It hides passive information and reusable instructions behind fake actions. That makes the model choose calls when the client could simply provide context, and it makes operational concerns noisier: permissions, logging, retries, and failures all look like tool execution even for things that should have been read-only context.

Can the same backend capability appear as more than one primitive?

Yes, but only if the interface semantics differ. A log store might expose recent logs as resources for inspection, and also expose a tool that runs a filtered diagnostic query. The distinction is not the backend system; it is whether the agent is reading named context, invoking work, or using a task template.

Tools, resources and prompts

Tools, resources and prompts are the main MCP primitives for exposing agent capabilities as actions, readable context, and reusable interaction templates. They separate what the model may execute, what the client may supply as information, and how a task should be framed, instead of forcing every capability into a function-like tool.

The problem is that agent integrations often blur different kinds of capability. A database query, a source file, and a security review instruction are not the same interface shape, even if all help the model complete a task. If everything is modelled as a tool, the model is asked to choose and invoke actions when it may only need context or a standard way to ask for work.

MCP separates these cases. A tool is an invocable operation, often with inputs and side effects, such as opening a ticket or running a build. A resource is something addressable and readable, such as a file, schema, log, or record. A prompt is a named template for an interaction, possibly parameterised, that packages instructions, structure, and expectations for a repeated task.

The trade-off is design discipline. Tools feel general, so teams often overuse them, but that makes permissions, error paths, audit trails, and model choice more complicated. Resources need clear identity and freshness semantics. Prompts need maintenance as product behaviour changes. The honest answer is not always obvious: a database capability might be a tool if it computes or mutates, but a resource if it exposes inspectable data.

Engineers meet this when defining an MCP server boundary. Repository files are usually resources; creating a pull request is a tool; a named security-review flow is a prompt that may refer to resources and suggest tool use. A good interface lets the client provide context directly, lets the model request real actions explicitly, and keeps reusable task framing visible rather than buried inside tool descriptions.

Go deeper

Agents & MCPTools, resources and promptsChoose the right MCP primitive for a capability instead of making everything a tool.Open the lesson

Common questions

How do I decide whether something should be a tool or a resource?: Ask whether the model is requesting an operation or reading context. If invocation performs work, changes state, calls another system, or can fail like an action, use a tool. If the capability is mainly something to inspect, quote, compare, or include in context, model it as a resource.
What is the difference between a prompt and a tool description?: A tool description tells the model when and how to call one operation. A prompt is a reusable task frame, such as a review, migration, or triage workflow. It can combine instructions, parameters, expected output shape, and references to resources or tools without pretending to be an executable action itself.
Why is making everything a tool a bad design?: It hides passive information and reusable instructions behind fake actions. That makes the model choose calls when the client could simply provide context, and it makes operational concerns noisier: permissions, logging, retries, and failures all look like tool execution even for things that should have been read-only context.
Can the same backend capability appear as more than one primitive?: Yes, but only if the interface semantics differ. A log store might expose recent logs as resources for inspection, and also expose a tool that runs a filtered diagnostic query. The distinction is not the backend system; it is whether the agent is reading named context, invoking work, or using a task template.

Every term