---
title: Make AI Agents Call Your MCP Instructions Tool First
description: Adding a get_instructions tool isn't enough: Claude called it first in 1 of 24 runs. With a short hint it was 24/24 in Claude Code and Codex. The recipe.
canonical: https://spiritroom.app/blog/get-instructions-first-24-of-24/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/blog/get-instructions-first-24-of-24/ for agents. Index: /llms.txt

[Blog](/blog/) / [Onboard agents through MCP](/guides/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

**TL;DR**

- **This is a mock-server result.** A local stand-in served a real 99-tool production list and its real server instructions, plus one new `get_instructions(job)` tool. 232 runs, Claude Code and Codex, 18 Oct 2026.
- **A tool alone is not enough.** Without a hint, Claude called `get_instructions` first in 1 of 24 runs (1–20%) and Codex in 9 of 24 (21–57%).
- **With the full recipe, both agents went 24 of 24 (86–100%)** on calling it first, picking the right job and following the playbook's step 1.
- **Any one hint got the call made first.** A line in the instructions, a line in every tool description, or Claude's always-load flag each scored 12/12 to 18/18. They back each other up.
- **The always-load flag is what makes Claude cheap:** 6–7k tokens before the first call instead of 15–28k.
- **No false starts:** an off-topic prompt never triggered a server call, in 15 of 15 runs.
[The problem](#problem)[The recipe](#recipe)[Results: 232 runs](#results)[Which part matters](#which-part)[Where it still failed](#failures)[Grok and OpenCode](#other-agents)[How we measured](#how-we-measured)[FAQ](#faq)

## 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.

User request**→**get\_instructions(job)**→**playbook**→**playbook's exact step 1

## 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.

Claude, tool only

*1/24*

Codex, tool only

*9/24*

Claude, full recipe

*24/24*

Codex, full recipe

*24/24*

Job requests on the 99-tool mock, 18 Oct 2026. “All three” = called first, right job, followed step 1

| Agent and setup | Called first | All three | Tokens before first server call (median) |
| --- | --- | --- | --- |
| Claude, tool only (no hint) | 1/24 (1–20%) | 1/24 (1–20%) | 17.8k (the one run) |
| Claude, hint in instructions | 12/12 (76–100%) | 10/12 (55–95%) | 15.4k |
| Claude, hint in tool descriptions | 12/12 (76–100%) | 10/12 (55–95%) | 28.3k |
| Claude, always-load flag only | 18/18 (82–100%) | 17/18 (74–99%) | 7.5k |
| **Claude, full recipe** | **24/24 (86–100%)** | **24/24 (86–100%)** | **6.3k** |
| Claude, full recipe on a 4-tool server | 12/12 (76–100%) | 12/12 (76–100%) | 4.5k |
| Codex, tool only (no hint) | 9/24 (21–57%) | 9/24 (21–57%) | 42.8k |
| Codex, hint in instructions | 12/12 (76–100%) | 12/12 (76–100%) | 55.1k |
| Codex, hint in tool descriptions | 12/12 (76–100%) | 12/12 (76–100%) | 43.6k |
| **Codex, full recipe** | **24/24 (86–100%)** | **24/24 (86–100%)** | **43.8k** |
| Codex, full recipe on a 4-tool server | 12/12 (76–100%) | 12/12 (76–100%) | 40.0k |

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.

**Want agents to start right on your server?**

We run your users' real jobs through Claude Code, Codex and the other apps they use, find where agents start wrong, and test the fix until it holds across runs.

[Book a pilot →](/#contact)

## 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?](/blog/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](/blog/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

Failures and causes, mock runs, 18 Oct 2026

| Failure | Where | Cause |
| --- | --- | --- |
| Didn't call `get_instructions` first | No hint: Claude 23/24, Codex 15/24 | Nothing told the agent to |
| Asked “which product do you mean?” and made no call | Codex, vague request, no hint 2/2 and instructions hint 1/1 | Codex's first request doesn't mention the server, so on a vague request the model may never search and never sees a hint. The full recipe got 4/4, too few runs to call it fixed. |
| Answered “what can you do?” from tool descriptions, no call | Claude, no hint 2/2, tool-description hint 1/1 | Arguably fine: it answered from what the server said |
| Right tool, wrong argument on step 1 | Claude, one job, 4 runs without the always-load flag | Kept its own default limit |

## 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](/blog/mcp-server-instructions-length/).

**Go deeper:** [How to onboard agents through your MCP server](/guides/onboard-agents-through-mcp/), [Claude Code tool search, seen from the wire](/blog/claude-code-tool-search-explained/), [Pass rates and confidence intervals for agent runs](/blog/agent-pass-rates-confidence-intervals/).

## 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](/blog/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](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1208), the question this post answers with runs.
- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp): tool search and per-tool loading.

## FAQ

### How do I make an AI agent call my MCP instructions tool first?

Expose a get\_instructions(job) tool described as "Start here", and tell the agent to call it in at least one place it reliably reads: the start of the server instructions, the start of every other tool description, or (for Claude Code) the anthropic/alwaysLoad flag on that tool. In our mock test the full recipe made Claude Code and Codex call it first in 24 of 24 runs each (86–100%).

### Is adding a get\_instructions tool enough on its own?

No. Without any hint, Claude Code called it first in 1 of 24 runs and Codex in 9 of 24. Agents go straight to the tool that looks closest to the request.

### What does anthropic/alwaysLoad do?

It is a \_meta flag on a tool that tells Claude Code to load that tool's full definition up front even when tool search is on. On get\_instructions it let Claude call the tool in its first model request, at 6–7k tokens before the first call instead of 15–28k with a search round trip. Codex ignores it.

### How long should MCP server instructions be?

Short. Our recipe text was 728 characters, about 170 tokens. Claude Code cuts instructions at 4,096 characters and Grok Build at about 2,048, so stay under 2,000 and put the hint first.

### Does the hint make agents call the server when they shouldn't?

Not in our runs. An off-topic prompt (a poem request) produced no server call in 15 of 15 runs across every setup.

### Does this work in Grok and OpenCode?

Smaller tests point the same way: in Grok Build the line in every tool description fixed a case where the instructions arrived too late (2/2 runs), and OpenCode 2 called get\_instructions in 2/2. Two runs per row only shows direction, not a rate.

**Want agents to start right on your server?**

We run your users' real jobs through Claude Code, Codex and the other apps they use, find where agents start wrong, and test the fix until it holds across runs.

[Book a pilot →](/#contact)

## Keep reading

- Up[How to onboard AI agents through your MCP server (guide)](/guides/onboard-agents-through-mcp/)
- Related[Do AI agents read your MCP server instructions? Tested in Claude Code, Codex, Grok and OpenCode](/blog/do-agents-read-mcp-server-instructions/)
- Related[How long should MCP server instructions be? Why 115,000 characters reached the model as 2,067](/blog/mcp-server-instructions-length/)
- Related[Claude Code tool search, seen from the wire: the model picks your tool from its name](/blog/claude-code-tool-search-explained/)
- Related[“10 of 10 passed” isn't 100%: reporting agent test results with confidence ranges](/blog/agent-pass-rates-confidence-intervals/)