MCP Tools vs Resources vs Prompts: What to Expose to an AI Agent

When a team first wraps an internal platform in MCP, the result almost always looks the same: forty tools named get_x, list_x, create_x, and update_x, plus a few things that should never have been tools at all. The model gets lost, picks the wrong getter, and burns context reading giant responses it only needed a fragment of. The Model Context Protocol defines three root primitives — tools, resources, and prompts — because those are three genuinely different relationships an agent can have with your system. Mapping your capabilities onto them correctly is most of the design work.

Tools: verbs with side effects

A tool is a function the model can call: it takes structured input, executes, and returns structured output or text. Tools are the right choice when the agent needs to do something, especially something with a side effect or a computation.

{
  "name": "refund_payment",
  "description": "Issues a full or partial refund against a captured payment. Requires the refund:write scope. Safe to retry with the same idempotency key.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "payment_id": { "type": "string" },
      "amount_cents": { "type": "integer", "minimum": 1 },
      "reason": { "type": "string", "enum": ["customer_request", "duplicate", "fraud"] }
    },
    "required": ["payment_id", "reason"]
  }
}

Signs something belongs in tools:

• It maps to a non-GET operation or an expensive computation.
• The answer changes state, or depends on live data at call time.
• Inputs are parameters rather than a document address.

Resources: readable, addressable context

A resource is data the client or model can read, identified by a URI. Resources are nouns: documents, records, configuration, log streams. They come in two shapes: static URIs like service://health/status and parameterized templates like orders://{order_id}.

{
  "uri": "orders://ord_8821",
  "name": "Order ord_8821",
  "description": "Full order record including line items, payment state, and fulfillment timeline.",
  "mimeType": "application/json"
}

The distinction that matters: a resource is pulled on demand and typically read into context as data, while a tool is invoked. When an agent needs to inspect an order before deciding, reading the resource is cheaper and more accurate than calling a get_order tool whose text output gets truncated into the conversation.

Signs something belongs in resources:

• It is a read of a stable, addressable thing.
• The client UI might show it directly (clients render resource lists and attachments).
• It is reference material the model should have available without deciding to "call" anything.

A common mistake is exposing every GET endpoint as both a resource and a tool. Pick resources for the documents humans also read (the API reference, the status page, the current user's entitlements) and keep the rest as tools only when the agent must actively query with computed parameters.

Resource templates: parameters without a tool

Templated resources let the client offer URI completion and still avoid a hand-written getter tool:

{
  "uriTemplate": "logs://{service}/{date}",
  "name": "Service daily logs",
  "mimeType": "text/plain"
}

The model fills service and date; the host fetches. Use templates when the address space is large and enumerable by pattern.

Prompts: packaged workflows

A prompt is a reusable, parameterized instruction template the server contributes. Where tools and resources expose capability, prompts expose procedure: the agreed way your team wants a task done.

{
  "name": "triage_incident",
  "description": "Walks an on-call engineer through triaging a service alert: gather recent deploys, correlate errors, draft an incident channel summary.",
  "arguments": [
    { "name": "service", "required": true },
    { "name": "alert", "required": true }
  ]
}

When the user selects it, the server returns a prepared message sequence, often pre-wired to the right resources and tools. Prompts are the answer to "every agent reinvents our runbook differently": encode the runbook once, on the server, where you can update it without touching clients.

Signs something belongs in prompts:

• It is a multi-step workflow with a known good order.
• Junior engineers are told to follow a checklist for it.
• The wording itself is the value (compliance phrasing, support tone, review rubrics).

The decision in one table

Two more primitives worth knowing

Roots and sampling round out the model, and both are commonly ignored in first implementations. Roots let a client expose its own filesystem or document boundaries to the server, so a local MCP server knows which project it operates on without configuration. Sampling lets a server request a model completion from the client, useful when a tool needs an LLM sub-step but must not carry its own API key. Neither replaces tools, resources, or prompts; they handle the edges around them.

How an OpenAPI spec maps onto all three

A single API specification describes all three relationships at once, which is why generating an MCP server from one spec works so naturally:

• Every mutating and query operation becomes a tool with the operation's JSON Schema as its input.
• The document itself, plus stable read-only entities teams reference constantly, become resources.
• The workflows your docs already describe in prose ("how to take an order through fulfillment") are candidates for prompts, authored once alongside the spec.

The spec stays the source of truth, and the three primitives stop being three things to maintain by hand. That argument is developed in your API already describes the tools your agent needs, and the human-versus-agent framing is in one spec, two audiences. You can see the tool and resource inventory a spec produces in the online demo.