Good MCP instructions make a cheap model find answers faster

The payoff, measured

I ran claude-haiku-4.5 against the live trip2g MCP endpoint. Seven retrieval questions, three times each, in two variants: with the docs-base instructions note in the system prompt, and with a bare "you have tools, use them" line instead. Real tool execution against the real docs.

The headline is the last row read together with the rest. Accuracy is a tie. The instructions buy efficiency, not correctness: fewer round-trips to the same answer, and far fewer of those round-trips ending in a full-note dump.

That last metric is the one I care about most. A "dump" is when the model reads a whole note instead of the one section it needed. On this base a section is a few hundred tokens and a whole note can be fifteen thousand characters. Without the instructions, Haiku dumped a full note 1.6 times per question on average. With them, less than once. The instructions teach the model to read the section, and it listens.

The second model told a different story

Then I ran the exact same A/B on gpt-5.4-nano. The direction flipped on the metric that matters most for cost.

nano barely benefits, because nano was already doing the right thing. Without any instructions it read by section 95% of the time and dumped a whole note only half as often as Haiku managed even with them. There was almost no waste for the instructions to remove. So the instructions' main effect was to add their own few hundred tokens to every turn and nudge nano to explore a little more, which pushed tokens up, not down.

The lesson is not "the instructions are bad." It is that the instructions are a correction for a wasteful default, and nano did not have one. Haiku, left alone, reads whole notes to be safe; the instructions fix that. nano reads by section on instinct; the instructions have nothing to fix and still cost context. If you could pick the model, you would skip the instructions for a disciplined one. But you rarely pick the model that connects to a public endpoint, so shipping the instructions is still the right call: they cap the damage from the wasteful models and cost the careful ones a few hundred tokens.

A couple of nano-specific quirks worth noting: it over-specifies its calls, passing about seven arguments to note_html (every id field plus match_id plus toc_path at once) where Haiku passes two. Harmless, since the server resolves any single identifier, but it shows nano does not try to trim the call itself. And nano leaned on expand more than Haiku did, doing more structural navigation before committing to a read.

What it costs in money

Tokens are the mechanism, but the bill is what you pay, and input and output are priced differently. I used Claude Haiku 4.5 at $1.00 per million input tokens and $5.00 per million output (Anthropic's published pricing), and gpt-5.4-nano at $0.05 input and $0.40 output (the OpenRouter rate at run time).

(Per query: Haiku $0.0220 without vs $0.0204 with; nano $0.00078 without vs $0.00100 with.)

Two things surprised me here, both worth stating plainly.

First, input dominates the bill, not output. In this workload input tokens are around 80% of the cost, even though output is priced five to eight times higher per token. The reason is structural: every section or note the model reads comes back as input on the next turn, so a big read is a big input charge, while the model's own answers are short. What moves money is the number of round-trips and how much each read dumps into context, which is exactly what the instructions control.

Second, the instructions themselves are a recurring input cost. They ride in the context on every call, so the real question is whether the per-call saving beats the per-call cost of carrying them. For Haiku it does: cutting a quarter of the tool calls removes more input than the instructions add, so the guided run is about 8% cheaper, roughly $1.68 less per thousand queries. For nano it does not: nano was already frugal, so the instructions remove little while adding their own weight, and the guided run costs about 29% more, roughly 22 cents more per thousand queries.

So the instructions are not free, and on an already-careful model they are a small net cost. They earn their keep on the wasteful models, where they cut both the round-trips and the whole-note dumps that actually drive the bill. Since you do not choose which model connects to a public endpoint, paying a few cents per thousand queries on the frugal ones to cap the expensive tail is a trade worth making.

How the instructions reach the model

One honest limit on all of the above: this benchmark puts the instructions in the model's system prompt directly. It does not run a real MCP client handshake. So strictly, I measured "the instructions are in context", not "a real client fetched them and showed them to the model".

That is a fair stand-in, because of where the instructions land in a real setup. initialize.instructions is a standard field in the MCP protocol: a spec-compliant client fetches the connected server's instructions during the connection handshake and surfaces them into the model's context automatically. Nobody pastes the instructions into the prompt; the client does it on connect. trip2g returns the docs-base instructions in exactly that field (internal/case/mcp/resolve.go:154). Putting the instructions in the system prompt for the A/B models what a well-behaved client does with them.

I designed that mechanism a while ago and, embarrassingly, had never checked that a real client actually picks the field up. So I ran a canary. I ran a clean Claude Code with my plugins disabled (on the flat subscription; unset ANTHROPIC_API_KEY before launching, or it bills the metered console path and stops on an out-of-credit error). The plugins-off part is the whole point: with my plugins loaded, one of them could have injected the instructions into context, but with none loaded nothing else can put them in front of the model except the MCP client itself. I registered the base as an HTTP MCP server and asked it, without pasting anything: "what connection instructions did the trip2g-docs server give you at startup?" It quoted the instructions back verbatim, under a heading it labelled "MCP Server Instructions": the identity line, the four-step retrieval loop, and the worked federation example, word for word from docs/_mcp_initialize.md. Since I never put that text in the prompt, the only way it reached the model was the client auto-surfacing initialize.instructions. The mechanism works. (One race worth noting: on a cold headless start the server can still be connecting when the first turn runs, and then the model correctly reports no instructions yet. Force the connection with one tool call first, or let it warm up.)

And it drives the loop end to end, not just recites it. On "how do I set up federation with a private peer using an HMAC secret", the tool trace was search("federation private peer HMAC secret setup") followed by note_html(pid=658, toc_path=["Adding a private peer (two-step exchange)"]). That is the taught loop exactly: search for a pointer, then read one section by its toc_path, no whole-note dump. It answered correctly and cited the note.

So the delivery path is real, not assumed: the canary proves the client auto-surfaces the instructions, and the federation trace proves the model then follows them against the live base. The A/B is still the part that measures the effect size: how much the instructions shift behavior versus a model left to its own instincts, which the without-instructions arm shows drills down some of the time anyway. Delivery confirmed live; magnitude quantified by the A/B. (Codex I left alone: headless it is slow and token-heavy, and a bounded check was not the place to wire it up.)

How the instructions earn it

The instructions teach one loop, and the loop is the whole trick:

1. search(query) returns pointers, not documents. Each hit carries a toc_path: a breadcrumb to the exact section that matched.
2. note_html(pid=N, toc_path=[...]) reads only that section. A few hundred tokens instead of the whole file.
3. expand(pid=N) walks the table of contents one level at a time when the pointer is soft, so the model can navigate to the right section instead of guessing.
4. Read the whole note only when expand shows it has no sections worth drilling into.

A bare model, given the same tools, tends to search and then read the whole top result to be safe. That works, and it is expensive. The instructions flip the default: pull the section first, fall back to the whole note last. On the federation question, the guided model answered in 2.7 calls and never dumped a note; the bare model took 5.3 calls and dumped one almost every time.

The other half of the instructions is guardrails written from how the tools actually fail. On this base a wrong toc_path does not raise an error. It silently returns the whole note. (This has since been fixed: a missed pointer now fails loud, with a "section not found" error and a nudge toward the top-level sections, PR #109. But the instructions were written for the old silent behavior, and as a technique the guardrail still holds.) So the instructions tell the model: if a section read comes back much longer than a section, your pointer missed, call expand and read the real heading, do not retry blind. That one instruction turns a silent 15,000-character mistake into a cheap recovery.

The honest parts

The instructions are not magic, and pretending otherwise would waste your time.

The bare model was not helpless. On its own it did the section read about a third of the time. Haiku knows toc_path exists once it sees the schema (perhaps because Anthropic wrote about exactly this, see the Contextual Retrieval hypothesis in the appendix); the instructions just make precise reading the habit instead of the exception.

Accuracy did not move. Both variants found the right note on every retrieval question. If your search is weak, an instructions note will not save you. trip2g has a hybrid keyword-plus-vector search that already lands the right note reliably, so the instructions had nothing to fix there and everything to fix in how the note got read.

One question cost more with the instructions than without. On "how do I publish a vault", the guided model kept drilling for the exact section (7+ calls) while the bare model stopped at a coarser answer sooner. Biasing toward precise section reads occasionally costs an extra call. It is a real trade, small, and worth it for the dump reduction everywhere else.

And one question was a wash by design, at least for Haiku: "what does expand do" got answered from memory by both Haiku variants, because the model already knows what "expand" means in the abstract. A generic-knowledge question is not a retrieval test, so I scored it separately. nano, for what it is worth, searched even for that one rather than trusting its memory.

Every knowledge base is different, so describe yours

There is no one true way to search a knowledge base. Mine is hybrid keyword-plus-vector with a section-drill-down loop, but yours might be pure RAG over vector chunks, a wikiLLM walking a wikilink graph, plain full-text, or some mix of all of them. Each is structured differently and rewards a different retrieval technique. An agent that connects cold cannot know which one it is looking at, so it guesses, and guessing is where the tokens and the wrong answers come from.

trip2g's answer is to let the base author write the manual. You know how your base is built, so you write a short navigation instruction that describes how to search this base: its retrieval loop, its tools, its conventions, its failure modes. The agent stops guessing because you have handed it the technique. This benchmark measures one such instructions note, but the point generalizes: the instructions are not trip2g-specific magic, they are you writing down the search method for your own knowledge so a connecting agent inherits it.

And it is delivered for free. As shown above, a compliant client auto-surfaces this instruction through the MCP initialize.instructions field the moment it connects, so every agent that ever talks to your base starts with your manual already in context. If you run a base, the practical steps are in the dev note docs/dev/mcp_instructions_guide.md ("How to write good MCP instructions for your base"), and the instructions note this benchmark tested is a worked example at docs/_mcp_instructions.md.

Why cheap Claude models take to this

A hypothesis, not a proven claim, for why even the without-instructions Haiku reads by section as often as it does. Anthropic's Contextual Retrieval prepends each chunk's situating context, its section and heading, before embedding it, and the reference implementation generated that context with Claude 3 Haiku. So "this paragraph lives under this heading in this document" is a shape Claude models were trained to produce and consume. trip2g surfaces exactly that as the toc_path breadcrumb on every search match. The guess: toc_path is a familiar affordance the moment a Claude model sees the schema, which is why it drills down by section without being told. The instruction does not teach a foreign trick, it makes an already-familiar move the default rather than the exception.

Method, so you can redo it

Models: claude-haiku-4.5 and gpt-5.4-nano over OpenRouter, tools set to the live MCP search, note_html, expand, similar. Variant A's system prompt was the instructions note at docs/_mcp_initialize.md with its frontmatter stripped, exactly what the MCP initialize response serves. Variant B's was a single generic line. Eight questions spread across federation, publishing, access control, the token-economy tools, and Telegram; three runs each; forty-eight runs per model. A "dump" is a note_html result over 6,000 characters. Total spend was about $0.92 for Haiku and $0.04 for nano.

The full tables, per-question breakdowns, raw runs, and the harness are in the dev notes: 2026-07-02_mcp_haiku_ab.md, 2026-07-02_mcp_haiku_ab_results.json, and 2026-07-02_mcp_nano_ab_results.json.

Write your own

If you run a trip2g base, give it its own initialize instructions note. Lead with what the base is, teach the search then toc_path then expand loop, show one worked example with a real note id, and write the guardrails from your tools' real failure paths. Keep it tight; a cheap model degrades under a wall of text. The full recipe, with the shadowing gotchas and a live validation checklist, is in the dev note docs/dev/mcp_instructions_guide.md (ships with the instructions note itself).

The upside is asymmetric. The instructions cost you an afternoon once and a few hundred tokens per connection. In return, a wasteful model like Haiku pays a quarter less to find its answers, and a careful one like nano is no worse off on the metric that decides success. When you cannot choose which model connects, that is the trade you want.