Your MCP server is a prompt

An MCP server looks like an API, and it is tempting to write it like one: terse names, a one-line description, an error code when something breaks. But the reader on the other end is not a developer with the docs open. It is a model deciding, one turn at a time, which tool to call, what to pass it, and what to do when it fails. Everything it knows about your server is text you wrote.

Three parts of that text do most of the work: whether your content is exposed as a tool or a resource, how each tool describes itself, and what an error tells the model to do next. A fourth, checking that Claude Code can see the server at all, takes two minutes and saves an hour of rewriting descriptions for a server that never connected.

Tools act, resources are read

The MCP specification gives the two primitives different owners. Tools are model-controlled: the model discovers and invokes them “based on its contextual understanding and the user’s prompts.” Resources are application-driven, with the host application “determining how to incorporate context based on their needs”, and each one is identified by a URI.

Almost anything can be a tool, so that is the wrong question. The useful one is whether the model needs to decide to fetch this, with arguments, at a moment only it can judge. If not, and the content is something Claude would otherwise go looking for, a resource is the better shape.

A database schema is the standard example. Exposed only through tools, every session starts the same way: Claude calls list_tables, then describe_table on three or four candidates, before it writes a single query. Each of those calls is a round trip spent rediscovering something that changes once a month. Exposed as a resource template, db://schema/{table}, the schema can be put in front of the model directly, and the exploration never happens. Stable reference content as resources is how you cut exploratory tool calls.

Resource templates use URI templates, so one entry covers every table. Resources can also carry annotations the host may use when deciding what to include: an audience of user, assistant or both, a priority from 0 to 1, and a lastModified time.

The line runs the other way too. A “read” that changes state, such as marking a notification seen, is a tool whatever it is called.

A description is the tool’s only documentation

Anthropic’s own guidance on tool definitions does not hedge:

Provide extremely detailed descriptions. This is by far the most important factor in tool performance.

Claude docs, Define tools

A description should say what the tool does, when to use it and when not to, what each parameter means, and what the tool does not return. The same guidance suggests at least three or four sentences for each tool. The failure it prevents is easiest to see with two tools that sound alike.

{
  "name": "search",
  "description": "Search orders.",
  "inputSchema": { "type": "object",
    "properties": { "query": { "type": "string" } } }
}
{
  "name": "get_order",
  "description": "Get an order.",
  "inputSchema": { "type": "object",
    "properties": { "id": { "type": "string" } } }
}

{
  "name": "orders_search",
  "description": "Finds orders by customer email, date or status and
    returns up to 20 summaries: order ID, date, status and total.
    Use it when you do not have an order ID yet. It does not return
    line items or shipping details; for those, call orders_get with
    an ID from these results. Dates are ISO 8601, e.g. 2026-09-01;
    relative dates such as 'last week' are rejected.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_email": { "type": "string",
        "description": "Exact address, e.g. ana@example.com" },
      "placed_after": { "type": "string", "format": "date",
        "description": "Earliest order date, inclusive, ISO 8601" },
      "status": { "type": "string",
        "enum": ["pending", "shipped", "delivered", "refunded"] }
    }
  }
}
{
  "name": "orders_get",
  "description": "Returns one order in full: line items, shipping
    address, payment status and refund history. Use it only when you
    already have an order ID, usually from orders_search. It does not
    search: an unknown ID returns a not-found error, not similar orders.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string",
        "description": "Order ID in the form ORD-123456" }
    },
    "required": ["order_id"]
  }
}

One difference from the Claude API is worth knowing. A Claude API tool definition accepts an input_examples field for format-sensitive inputs. The MCP tool definition has name, title, description, inputSchema, outputSchema and annotations, and no field for examples, so on an MCP server the example values belong in the descriptions.

And when two tools stay confused however well they are described, the fix may be one tool. The same guidance recommends consolidating related operations, because “fewer, more capable tools reduce selection ambiguity.”

An error is an instruction

The specification defines two ways for a tool call to fail, and they are for different things.

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [ { "type": "text",
      "text": "Failed to fetch weather data:
        API rate limit exceeded" } ],
    "isError": true
  }
}

The second channel is the one you write for the model. It arrives as a tool result with the error flag set, so whatever you put in its content is what the model reasons over when it decides what to do next. Claude’s documentation puts the standard plainly: instead of a generic “failed”, say what went wrong and what to try next, as in “Rate limit exceeded. Retry after 60 seconds.”

In practice that means every execution error answers three questions: what kind of failure this is, whether trying again can help, and what the model should do instead. The field names below are a convention, not part of the specification; what matters is that the answers are there, in words the model can act on.

Compare those with a stack trace or Error 403. Both are accurate, and neither tells the model whether to wait, fix its input, try a different tool or stop. A model left to guess tends to retry, which is exactly the wrong move for two of the three cases above.

Not every disappointment is an error

A search that legitimately finds nothing succeeded. Return it as a normal result, and make it useful: “No orders for ana@example.com since 2026-09-01. Orders older than 90 days are archived; search with an earlier placed_after to include them.” Flagging an empty result as an error invites the model to treat a correct answer as a fault to work around.

Check the server is actually there

Before rewriting a description because Claude ignores a tool, confirm Claude Code has the tool at all. Where the server is configured, and how its credentials stay out of the repository, is covered in Every Claude Code setting has an address.

Try it

Decide the fix before opening each one.

Sources: the MCP specification on tools and resources (2025-06-18); Claude’s documentation on defining tools and handling tool calls; Anthropic Engineering, Writing tools for agents; the Claude Code MCP documentation. Checked September 2026.

More on this

• Every Claude Code setting has an address — The usual mistake with Claude Code configuration is a good instruction filed in the wrong place. Two questions tell you where it belongs.
• Your practice percentage is measuring the wrong thing — Any tool that re-asks the questions you got wrong poisons its own accuracy statistic. Here is how far off it gets, measured.
• A 720 is not 72% — Scaled scores and weighted blueprints both break the arithmetic people do in their heads.