Blog / Onboard agents through MCP

Make the agent read your playbook first: 24 of 24 runs in Claude Code and Codex

You wrote a playbook for agents. You exposed it as a tool. And the agent skipped it and went straight for the tool that looked closest to the user's words, in 23 of 24 runs. Here's what changed that to 24 of 24, measured on a mock of a 99-tool production server.

Leonid Bugaev · Published 21 Oct 2026

The problem: agents skip your playbook

A big MCP server needs a manual. Which tool comes first for this job, which arguments matter, what never to do. Server authors write that down, and a common pattern is to serve it from a tool: get_instructions, “start here”, the agent calls it and knows what to do.

Except the agent doesn't. Given a user request like “plan this week's run without spending”, it looks for the tool whose name matches the request and calls that. The playbook sits unread.

We wanted numbers, not impressions. So we took a mock of a 99-tool production server, added one get_instructions(job) tool, and measured what it takes for Claude Code and Codex to call it first, pick the right playbook and then actually follow it.

The recipe that worked

1. Start the server instructions with the hint, and keep them short. For example: “Before doing anything with Acme, call get_instructions with the job you are doing (plan_run, review_new or check_proposals), or with no job if unsure.” Ours was 728 characters, about 170 tokens. The production server's own text was 5,092 characters.
2. Add get_instructions(job) with one optional choice argument, a one-line description of every job, and list. Describe it as “Start here”.
3. For Claude Code, mark it always-loaded with _meta, so the model sees it without searching.
4. Optionally, start every other tool description with “Before your first call, call get_instructions once.” It's about 12 tokens per tool.
5. Give each playbook a concrete first step. Agents followed exact steps, down to odd argument values.

{
  "name": "get_instructions",
  "description": "Start here. Returns the playbook for a job. plan_run: plan a run within a budget, without spending. review_new: review what came in since the last check. check_proposals: review pending proposals. list: list the jobs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "job": { "type": "string", "enum": ["plan_run", "review_new", "check_proposals", "list"] }
    }
  },
  "_meta": {
    "anthropic/alwaysLoad": true,
    "anthropic/searchHint": "start here, playbook, instructions, how to use"
  }
}

Job and tool names here are illustrative. The tested server used its own.

Results: 232 runs, Claude Code and Codex

Each playbook's step 1 asked for a call an agent wouldn't make on its own, such as a balance check with movements: 3 or an activity feed with limit: 37. If that exact call appeared, the agent had read and followed the playbook. Ranges are 95% Wilson intervals.

Two controls matter as much as the headline. On an off-topic request (a poem), no agent called the server in any setup: 15 of 15 runs. And on vague requests (“What can you do for me with Acme?”) the full recipe got get_instructions called first in 4 of 4 runs for both agents (51–100%), against 2 of 4 (Claude) and 1 of 4 (Codex) with no hint.

Which part of the recipe matters

A hint is required

With no hint, Claude went straight to the most relevant-looking tool in 23 of 24 runs, and Codex in 15 of 24. Codex sometimes found get_instructions anyway, because it searches all tool descriptions in code and the description says “Start here”.

Any one hint is enough to get the first call

The instructions line, the tool-description line and Claude's always-load flag each scored 12/12 to 18/18 on calling first. None is strictly needed on its own. Keep more than one, because each agent app reads a different channel: see do agents read MCP server instructions?

The always-load flag is what makes Claude cheap

With it, Claude saw get_instructions in its first request and called it straight away: one model request and 6–7k tokens before the first call. Without it, Claude had to search for the tool first: 2–3 requests and 15–28k tokens. The tool-description hint alone was the most expensive at 28.3k, because the server's long original instructions were still sent too.

The job list picks the right playbook

Whenever get_instructions was called on a job request, the job was right on the first try in every setup: Claude 79 of 79 (95–100%), Codex 70 of 70 (95–100%). A one-line description per job was enough.

Following the playbook is very reliable, not perfect

Across every setup with at least one hint, Codex sent the exact step-1 call in 60 of 60 runs (94–100%), Claude in 74 of 78 (88–98%). Claude's four misses were all on one job without the always-load flag: right tool, but its own default limit instead of the playbook's.

Server size stops mattering

The 4-tool and 99-tool versions scored the same once the recipe was in (12/12 and 24/24). The small server only saved tokens. More on tool count in how many MCP tools is too many.

Codex pays about 40k tokens either way

In its default code mode, Codex's first model request doesn't name the server at all. The model searches all tools first and only then sees descriptions, so 40–55k tokens go by before the first server call whatever the server does.

Where it still failed

What about Grok and OpenCode?

An earlier, smaller test on the same tool list (two runs per row, so direction only):

• Grok Build 1.0.60: with the hint only in the instructions, 1 of 2 runs. In the other, the instructions arrived too late. Adding the line to every tool description fixed it: 2 of 2, first call, followed. Grok also cuts instructions at about 2,048 characters.
• OpenCode 2.0.31: 2 of 2 with the instructions hint. Keep get_instructions's schema tiny, because OpenCode 2 shows only some tools up front, cheapest schemas first.

If your users run Grok or OpenCode, keep the tool-description line. The instruction cutoffs per app are in how long MCP server instructions should be (coming soon).

Go deeper: How to onboard agents through your MCP server, Pass rates and confidence intervals for agent runs.

How we measured

• Server: a local stand-in serving a production server's real list of 99 tools and its real 5,092-character instructions, recorded from the live server on 16 Oct 2026, plus get_instructions(job) with three jobs and list. Tool results were small fixed answers. No live service, real data or credentials were involved.
• Setups: no hint; instructions hint (new 728-character text); tool-description hint; always-load flag (Claude only); full recipe; full recipe on a 4-tool server.
• Agents: Claude Code 2.1.302 on its default model with tool search on and no user settings or skills; Codex CLI 0.161.0 in its default code mode with high reasoning and every other MCP server switched off.
• Prompts: 15 neutral requests: 12 job requests (4 per job, half without the product name), 2 vague, 1 off-topic. None mentioned instructions or playbooks.
• Scoring: deterministic, from the server's call log and recorded model traffic. A run stopped when the step-1 call appeared or after 4 server calls. 232 runs between 12:40 and 13:10 Istanbul time (UTC+3) on 18 Oct 2026.
• Limits: a mock, so this shows how agents start a job, not how well they finish it. Runs aren't fully independent: for the full recipe, the two runs of a prompt made identical calls in 12 of 15 pairs (Claude) and 10 of 15 (Codex), so the ranges are somewhat optimistic. Counting the 12 distinct job prompts instead, all passed for both agents: 12/12, 76–100%. One model per agent.

The method behind these numbers is in how to measure MCP server quality.

Sources

• Spirit Room mock-server runs, 18 Oct 2026 (232 runs), and per-app capture tests, 16 Oct 2026.
• MCP discussion #1208: instructions injection on server first usage, the question this post answers with runs.
• Claude Code MCP documentation: tool search and per-tool loading.