How is a resource different from a tool that returns text?

A resource is a read of addressable context; a tool is an operation the agent asks the server to perform. If the server only returns existing content, use a resource. If it changes state, calls an external side effect, or represents an action request, use a tool.

Does exposing data as resources reduce token usage?

It depends on what changes. The returned content still consumes context tokens when the model reads it. The saving is usually in removing a tool-call step and making repeated context attachment cleaner. If the same large text is still included every time, the token cost remains.

When should I use a resource template?

Use a template when many resources share the same shape and differ only by an identifier, such as an invoice, customer, or document id. Listing every concrete URI makes discovery noisy and brittle. A template tells the client the pattern without pretending every possible item must be enumerated.

Exposing data as resources

Exposing data as resources is the MCP pattern of publishing read-only context behind stable URIs so an agent can discover and read it without treating the read as an action. It separates passive information retrieval from tool execution, making traces clearer and keeping mutations confined to tools.

The problem is that agents often need background material before acting: policy text, repository files, schemas, product documentation, customer profiles, or similar context. If every read is wrapped as a tool, the trace makes a harmless lookup look like an operation, and the model spends an extra action step fetching something that was never meant to change state.

In MCP, a server exposes resources as addressable items. A client asks what is available with `resources/list`, then fetches one with `resources/read` using a concrete `uri`, such as `file:///repo/README.md` or `docs://policies/refunds`. Some resources are fixed names; others are templates, such as `customer://{customer_id}/profile`, where the client fills in the variable before reading.

The important boundary is read-only behaviour. A resource read should return content, not update counters, mark records as viewed, create audit entries, or trigger workflow. Those belong in a tool call. Resources also do not make content free: a large document still becomes context the model must process. They remove an unnecessary action round trip, not the cost of reading the text.

Engineers meet this when building MCP servers or debugging agent traces. Product docs, repo files, database metadata, policy pages, and other passive inputs fit under `resources`; order creation, ticket updates, emails, and writes fit under tools. A common mistake is listing hundreds of concrete row URIs instead of exposing a template. Another is repeatedly returning the same README after tool calls instead of attaching it once as context.

Go deeper

Agents & MCPExposing data as resourcesServe read-only context without turning it into a tool call.Open the lesson

Common questions

How is a resource different from a tool that returns text?: A resource is a read of addressable context; a tool is an operation the agent asks the server to perform. If the server only returns existing content, use a resource. If it changes state, calls an external side effect, or represents an action request, use a tool.
Does exposing data as resources reduce token usage?: It depends on what changes. The returned content still consumes context tokens when the model reads it. The saving is usually in removing a tool-call step and making repeated context attachment cleaner. If the same large text is still included every time, the token cost remains.
When should I use a resource template?: Use a template when many resources share the same shape and differ only by an identifier, such as an invoice, customer, or document id. Listing every concrete URI makes discovery noisy and brittle. A template tells the client the pattern without pretending every possible item must be enumerated.

Every term