Complete "Building Your First MCP Server" first to unlock this lesson.Go to previous lesson

Introduction

MCP primitives are the main design units that connect an AI application to external capabilities and context. When building an MCP server, the central design question is not how many endpoints to expose. It is deciding whether each capability should be represented as a tool, a resource, or a prompt. Choosing the wrong primitive can make an agent unsafe, make context difficult to discover, or force users to repeat instructions manually.

The three primitives have different control and interaction models. Tools are generally model-controlled: an agent can decide to call them when it needs an action or computation. Resources are generally application-controlled: the host application decides when to retrieve and present their content. Prompts are generally user-controlled: the user selects or invokes a reusable interaction template. These are common MCP design conventions, not merely different names for the same operation.

This lesson presents a practical selection method, contract design rules, and a small decision helper. The goal is to make primitive selection predictable before implementation begins.

A three-column diagram comparing MCP tools, resources, and prompts, with control flow arrows from model to tools, application to resources, and user to prompts

The Three Primitives

A tool represents an operation that the model or agent may request. The operation can read data, transform data, call a service, or cause a side effect. Examples include searching a ticket system, calculating shipping cost, creating a draft invoice, or cancelling a reservation. A tool should have a specific name, a clear description, a defined input schema, and an output that the model can interpret.

A resource represents addressable information identified by a URI. It is appropriate for documents, configuration, records, schemas, reports, or other context that an application can load and make available to the model. A resource may be static, such as a policy document, or dynamic, such as a customer record whose URI identifies a current entity. Reading a resource should be treated as context retrieval rather than an instruction to perform an action.

A prompt is a reusable interaction template with a known purpose. It can define suggested messages, arguments, and the expected structure of a task. For example, a support application may expose a prompt for summarizing a customer complaint, while a code review application may expose a prompt for reviewing a pull request. A prompt is not a replacement for a tool and should not hide an operation that changes external state.

Choosing the Right Primitive

Start by identifying what the user or agent needs to obtain. If the requirement is an action, calculation, lookup with parameters, or external side effect, begin with a tool. The fact that an operation only reads data does not automatically make it a resource. A parameterized search for current orders is often a tool because the model requests a computation and receives a result based on supplied arguments.

Choose a resource when the main value is retrievable context with a stable identity. A document such as a return policy, a database record URI, or a generated report can be represented as a resource when the application can decide when it should be loaded. Resources are especially useful when users need to browse, attach, cache, refresh, or inspect context independently of an agent decision.

Choose a prompt when the requirement is to package a repeatable conversation pattern for a user. A prompt can tell the model how to use available context, but it should not pretend to be an executable business operation. If a request says “help me prepare a refund request,” a prompt may structure the conversation. If it says “issue the refund,” a tool must perform the authorized operation.

A useful test is to complete the sentence “Who initiates this interaction?” If the model should decide when to invoke an operation, use a tool. If the host application should retrieve or attach information, use a resource. If the user should choose a prepared workflow, use a prompt. Some workflows legitimately use all three primitives in sequence.

Designing Strong Contracts

A good tool contract minimizes ambiguity. Its name should describe the operation, not the implementation. Its description should state when to use it, when not to use it, what permissions it requires, and what important constraints apply. Input fields should have explicit types, meaningful descriptions, validation rules, and bounded values where possible. A tool that accepts a free-form object for every request makes it harder for both models and servers to detect mistakes.

Tool outputs should distinguish successful data from failure information. Return structured results when the client needs to inspect fields programmatically, and include concise human-readable content when the result will be shown to a model or user. Do not report success merely because a request reached the server. For side-effecting tools, the result should make clear whether the operation was completed, rejected, partially completed, or only prepared as a draft.

Resource design depends on stable identifiers and predictable content. Use URIs that identify the domain object or document without embedding accidental implementation details. Decide whether a resource is immutable, refreshable, or versioned, and document how stale content is handled. A resource containing sensitive data also needs an authorization policy; a URI is an identifier, not permission to read the underlying data.

Prompt design should expose only arguments that users or applications can reasonably provide. A prompt description should state its intended outcome and required context. Keep operational instructions separate from user data, and avoid embedding claims that the model must treat as authoritative unless the application can maintain them. A prompt can recommend a tool call, but authorization and validation must remain in the tool and server layers.

Worked Example

Imagine a customer support application with three requirements. It must find a customer’s open orders, provide the current return policy, and guide an agent through a return conversation. The first requirement is a parameterized lookup against a live system, so it fits a tool. The second is an addressable document that the application can load when needed, so it fits a resource. The third is a repeatable user-selected conversation pattern, so it fits a prompt.

The following local JavaScript helper expresses that decision rule. It is not an MCP server and does not replace protocol registration. Its purpose is to make design reviews explicit before implementation. The result includes the chosen primitive and the reason that supports the choice.

javascript
function chooseMcpPrimitive(requirement) {
const text = requirement.toLowerCase();
if (text.includes("perform") || text.includes("create") || text.includes("update") ||
text.includes("delete") || text.includes("search") || text.includes("calculate") ||
text.includes("send") || text.includes("live")) {
return {
primitive: "tool",
reason: "The requirement describes an operation, computation, parameterized lookup, or side effect."
};
}
if (text.includes("document") || text.includes("policy") || text.includes("record") ||
text.includes("report") || text.includes("read") || text.includes("context")) {
return {
primitive: "resource",
reason: "The requirement describes addressable information that an application can retrieve and attach as context."
};
}
if (text.includes("guide") || text.includes("workflow") || text.includes("template") ||
text.includes("conversation") || text.includes("summarize")) {
return {
primitive: "prompt",
reason: "The requirement describes a reusable interaction pattern selected by a user or application."
};
}
return {
primitive: "review",
reason: "The requirement does not provide enough information to distinguish action, context, and interaction template."
};
}
console.log(chooseMcpPrimitive("search live open orders for a customer"));
console.log(chooseMcpPrimitive("read the current return policy document"));
console.log(chooseMcpPrimitive("guide an agent through a return conversation"));

The first call should produce a tool decision, the second a resource decision, and the third a prompt decision. The helper is intentionally conservative about ambiguity. A real design review should inspect authorization, freshness, user control, and whether the operation has side effects before registering anything.

Common Failure Modes

A frequent mistake is exposing every capability as a tool because tools are easy for an agent to call. This creates an oversized tool catalog and encourages the model to retrieve documents through operations that should have been browsable or application-controlled. Separate retrieval context from actions, especially when the context is stable and can be cached.

Another mistake is making a tool description vague. A name such as process_request does not tell the model whether it searches, approves, submits, or deletes something. Ambiguous descriptions increase incorrect calls and make authorization review difficult. State the operation, required inputs, important exclusions, and side-effect behavior directly.

A resource can also be designed incorrectly when its URI exposes secrets, depends on unstable database internals, or implies access without enforcing it. Use opaque identifiers where appropriate, validate authorization on every read, and define how missing, stale, or unavailable content is reported. For prompts, avoid treating a prompt as a security boundary. Instructions inside a prompt cannot replace server-side validation.

Finally, do not assume that combining primitives automatically creates a good workflow. Test whether the host exposes resources at the right time, whether users can understand prompt arguments, and whether tools reject malformed or unauthorized requests. Observability should record primitive name, validation outcome, authorization result, and failure category without logging sensitive values unnecessarily.

Summary

Tools are for operations, computations, parameterized lookups, and side effects. Resources are for addressable information that an application can retrieve and provide as context. Prompts are for reusable interaction patterns that users can select or invoke. Their differences concern both data shape and control ownership.

A reliable design process starts with the requirement, identifies who initiates the interaction, checks whether the result is an action or context, and then defines a narrow contract. For each primitive, descriptions, schemas, permissions, errors, and freshness behavior should be explicit.

When a workflow crosses multiple concerns, compose the primitives deliberately. A user may select a prompt, the application may attach a resource, and the model may call a tool. Keeping those responsibilities separate produces clearer behavior, safer authorization, and MCP integrations that are easier to test and maintain.

Lesson practice

Lesson Checkpoint

Review what you learned and get feedback on your work.

0/1
Answered · 0/1