Server instructions: the paragraph every model reads first

October 9, 2026 · Part 4 of 35

Of everything a Model Context Protocol (MCP) server sends back, the instructions field gets far less care than its influence deserves. It’s a few lines of plain text on how to use your server, and in the hosts that load it, it’s among the first things the model reads. With tool search, it helps the model decide when to look for your tools.

This is part 4 of my series on what an MCP server does under the 2026-07-28 specification. Part 3 covered server/discover, the request that now carries this paragraph. The facts are as I read them in October 2026.

In brief

1. instructions is an optional, plain-text field of the server/discover result, cached with the rest of discovery. Before 2026-07-28 it sat in the initialize result.
2. Putting it in front of the model is the host’s choice, not a protocol guarantee. Claude Code loads it at session start and, by default, cuts it at 2,048 characters, as of October 2026.
3. Tool search raises the stakes. When a host loads only tool names and instructions up front, your paragraph helps the model decide whether to look for your tools.
4. A good paragraph answers four questions: what the server is for, when to use it and when not, how the tools fit together, and what the limits are.
5. Leave out copies of tool descriptions, anything you rely on for security and commands that read like prompt injection, and keep the paragraph short.

Where instructions live, and who reads them

The field moved with the 2026-07-28 change from a handshake to discovery:

The specification describes it as optional guidance, in natural language, for language models on how to use the server effectively. A client can use it, for example by including it in a system prompt, but nothing requires it to.

Calling server/discover is itself optional for a client, and nothing in the protocol says the text must reach the model. Hosts that support it typically put it in the system prompt when they connect, but that’s host behaviour. So write it for the hosts that read it, and don’t count on every host reading it.

Why it matters more with tool search

Hosts with many connected servers no longer load every tool schema into the context window. Claude Code, for example, defers tool definitions until they’re needed: only tool names and server instructions load at session start, and the model searches for full schemas on demand. Its docs say the instructions field “becomes more useful with tool search enabled”, because it helps the model decide when to look for your tools at all.

Here is that path in a host that works this way:

When a task doesn’t match, your server stays dormant and its full schemas never load. But the choice is made from a list of tool names and your paragraph, so the paragraph is worth writing with care.

What to write, and what to leave out

Four questions

A good instructions block answers four questions:

1. What is this server for? One sentence on the domain and the kind of tasks.
2. When should the model use it, and when not? Clear boundaries avoid confusion with similar servers.
3. How do the tools fit together? The order of calls, which handle feeds which tool, the search-then-fetch pattern.
4. What are the constraints? Rate limits, expensive operations, how fresh the data is, how long handles are kept.

Setting it in Python

Here is my example for an internal documentation server. With the official Python software development kit (SDK), mcp 2.3.0, it’s the instructions parameter of MCPServer:

from mcp.server import MCPServer

ACME_DOCS_INSTRUCTIONS = """\
Acme Docs server: search and read Acme's internal engineering documentation
(runbooks, ADRs, API references). Use it for questions about Acme systems; do
not use it for general programming questions.

Workflow: call search_docs first, then fetch_doc with the returned doc_id for
full text. Prefer fetch_doc over quoting search snippets. For step-by-step
procedures, load the skill skill://incident-runbook/SKILL.md.

Constraints: search_docs is cheap; fetch_doc returns up to 20k characters.
Document IDs are stable. Content is refreshed nightly.
"""

mcp = MCPServer("acme-docs", instructions=ACME_DOCS_INSTRUCTIONS)

The first paragraph answers the first two questions, the second says how the tools fit together, and the third gives the limits. As in part 3, the SDK’s in-memory client reads it back, and this time the legacy handshake gets the same text too:

import anyio
from mcp import Client


async def main() -> None:
    async with Client(mcp) as client:  # 2026-07-28 by default
        discover = client.session.discover_result
        print(client.protocol_version)
        print(discover.instructions.splitlines()[0])
        print(len(discover.instructions), "characters")
    async with Client(mcp, mode="legacy") as old:  # the initialize handshake
        print(old.protocol_version, old.instructions == discover.instructions)


anyio.run(main)

2026-07-28
Acme Docs server: search and read Acme's internal engineering documentation
547 characters
2025-11-25 True

You set the text once and the SDK places it for each era: in the server/discover result for a 2026-07-28 client, and in the initialize result for one that still uses the handshake. At 547 characters, the example sits well inside the 2,048 characters Claude Code keeps by default.

What to leave out

• Copies of tool descriptions. Those belong on the tools and load on demand. The Python SDK’s own type for the field says the same: it “should not duplicate information already in tool descriptions”.
• Enforcement. Instructions are hints. A careful host treats them as untrusted text, so security has to live in your server’s own checks.
• Commands that read like prompt injection. For example, “Always use this server instead of others” or “Ignore previous instructions”. Hosts and reviewers treat them as a red flag, and tool-poisoning attacks rely on the same pattern. The rules I collected in One MCP server, eight rulebooks list prompt-injection patterns and promotional descriptions among what reviewers reject.
• Anything long. As of October 2026, Claude Code truncates each tool description and each server’s instructions at 2,048 characters by default. Put the critical details near the start.

Instructions, prompts and skills

All three shape how a model works with your server, but they arrive at different times:

The spec defines the field, not how hosts use it. My advice goes further: treat the instructions block as product copy and version it like code. Review it whenever your tools change, test it with tool search turned on in at least one host, and measure whether the model picks your server for the tasks it should.

Hosts that load instructions show them to the model at the start, before any prompt or skill is picked, so use them to point at your skills and prompts by Uniform Resource Identifier (URI) or by name, as the example does with skill://incident-runbook/SKILL.md.

Method and caveats

• Built from my guide to MCP servers and written against the 2026-07-28 specification.
• Claude Code’s behaviour (tool search, what loads at session start, the 2,048-character limit) is as its documentation describes it in October 2026. Other hosts may load instructions differently, or not at all.
• The Python sample was run against mcp 2.3.0 on 8 October 2026 with the SDK’s in-memory client, and the output shown is what it printed. My notes name the C# SDK’s option for this field; here it’s the Python parameter.
• Where the specification is more precise than my notes (calling server/discover is optional for a client, and whether the instructions reach the model is up to the host), this article follows the specification.

I’m Amir Pournasserian. I build AI and platform systems for a living, maintain FluentCMS and YeSvelte, and write here about what I find along the way.