Agent playbooks as MCP tools

How do you give production agents your team's real workflows without stuffing every tool into context? Write each recurring workflow down as a playbook with a typed contract, expose it through MCP as a tool, and put three small meta-tools in front of the whole catalog: one that searches it, one that returns a single playbook's schema, and one that executes a playbook with validated inputs. The agent's context then holds three tool definitions rather than hundreds, and it loads a procedure only when the task in front of it calls for one.

The problem is harder than it sounds because the missing piece is rarely capability. A frontier model can write the migration, read the stack trace and draft the pull request, and it rarely gets stuck on any of that.

It cannot know how this company does the job: which service owns the flag, which dashboard the on-call engineer opens first, which cleanup steps have to run in which order, and which check a reviewer will block on. That knowledge is procedural memory, and in most engineering organizations it lives in a few senior heads, a wiki page from two reorganizations ago, and the shell history of whoever did it last.

This guide covers what a playbook declares, why it should be a tool and not a prompt, how three meta-tools keep a large catalog usable, how central and repo-local playbooks share one catalog, and what every run should record. Who may call a playbook, and with which credential, is a separate question with its own guide: how to scope AI agent permissions. This guide assumes that check exists, and covers the procedure an agent follows once it has passed.

Why do capable agents still fail inside a mature codebase?

An AI agent dropped into a large organization behaves like a strong contractor on day one. It is fluent in the language and the frameworks, and it has no idea which of the four logging libraries in the monorepo is the current one. It guesses, the guess is plausible, and the pull request fails review for a reason nobody wrote down. Multiply that by every internal system the task touches and the agent spends its turns rediscovering what a tenured engineer knows by habit.

LinkedIn's engineering team reached the same diagnosis when it built CAPT, its Contextual Agent Playbooks and Tools framework, on MCP. Their write-up puts it plainly:

What they lacked wasn't intelligence. It was organizational context, access to internal tools, and structured guidance for LinkedIn-specific workflows.

We met the tool side of that problem on a different product. On Solarpunk, an agent that works across a leader's email, calendar, documents, CRM and ERP, direct tool calling held up until somewhere around thirty tools. Past that, selection went quietly wrong: the model picked a plausible tool from the wrong system and returned a confident result. The context cost was visible, and the wrong pick was the expensive failure, because nothing in the output said it had happened.

Those two findings point at one design. Encode the procedure so the agent does not have to guess it, and keep the catalog of procedures out of the context window until the agent needs a specific one. A playbook handles the first half and the meta-tools handle the second, so the rest of this guide takes them in that order.

What goes into a playbook?

A playbook is a written procedure with a contract attached. It names the task, the inputs it needs, the order of steps, the tools each step calls, and the conditions under which it stops. Most teams already have the raw material in runbooks and onboarding documents. The work is turning prose a human can interpret into fields an agent cannot misread.

These are the fields we write for every playbook, and what goes wrong when one is left out:

Field	What it holds	What breaks without it
Name and tags	A verb-first name and tags by function, such as experimentation, logs or deploys	Search cannot find it, and two teams write the same playbook under different names
Purpose	When to use it, and the near-miss tasks where it does not apply	The agent runs it on a task that looks similar and is not
Inputs	A typed schema with required fields and allowed values	The agent fills a missing parameter with a guess and runs against the wrong target
Preconditions	States that must hold before the first step	Cleanup runs on an experiment that is still ramping
Steps	Ordered instructions that name the tool each step calls	The agent improvises the order, and the order was the knowledge
Stop and escalate	Conditions where the run halts and hands back one question	A partial run carries on and reports the whole task as done
Verification	An independent check that the intended state now exists	"Done" means the last tool call returned without an error
Owner and version	A team and a version string	Nobody fixes it when the API underneath changes

The purpose field deserves more care than it usually gets. Write the near-misses into it: "use for removing a concluded experiment's code paths, not for pausing a live one." Search ranks on that text, and an agent choosing between two similar playbooks reads it before anything else. When the purpose only says what the playbook does, the agent has no way to rule it out.

The same four groups of fields, in the order the agent reads them:

This figure is a framework. The groups follow the order of the three meta-tools later in the guide: search reads the identity fields, the schema call returns the contract, and execution runs the steps and cannot finish without the exit fields. The figure lists fields and assigns no weights, and it does not describe any one company's format.

Hand-written runbooks are thinnest in the exit group. A person following a runbook notices when something looks wrong and stops. An agent following one keeps going unless the document tells it what "wrong" looks like.

Our guide on why AI agents report work as done covers what that costs once the run ends. Write the stop conditions as observable states, such as "the flag still has live traffic," and make verification read the result from a different path than the one that made the change.

Why expose a playbook as a tool and not as a prompt?

Teams usually try three other homes for procedure before they reach this one, and each fails in a specific way. A system prompt or a rules file is loaded on every request, so it grows until it crowds out the task. A wiki behind retrieval gets found when the words match, and what comes back is prose the agent must interpret. One MCP tool per workflow, all loaded at once, executes well until the tool list is long enough to degrade selection.

The table compares those options on the properties that matter in production:

Where the procedure lives	When the agent sees it	Can the agent execute it	Versioned with an owner	Holds up at hundreds of workflows
System prompt or rules file	Every request	No, it describes	With the repo, rarely owned	No, it fills the context window
Wiki page found by retrieval	When the search matches	No, it describes	Page history, loosely owned	Partly, but it returns prose
One MCP tool per workflow, all loaded	Every request	Yes	Yes	No, tool choice degrades
Playbook behind meta-tools	When the agent searches for it	Yes	Yes	Yes

A tool has a schema, so the inputs are checked before any step runs. The agent can decide for itself when to call it, chain it with other tools, and call it again from inside a larger task.

A prompt can do none of that, and it cannot be logged as an invocation, because nothing was invoked. The CAPT write-up describes the same move: each playbook is exposed to agents as a tool rather than as a prompt template, so agents decide when to invoke it and can combine it with other tools.

Structured inputs matter for a second reason. A playbook that takes experiment_key as a required string, and not "the experiment," forces the agent to find the key before it starts. If it cannot, the schema validation fails at the door, which is a much better place to fail than step four of a cleanup. We use the same idea for model output with structured output, and the playbook contract applies it to the agent's arguments.

How do three meta-tools keep a large catalog usable?

Loading every playbook as its own tool brings the Solarpunk problem back at a larger scale. The CAPT write-up gives the practical ceiling from their side:

Most MCP clients work best with only a few dozen tools at a time.

The fix is to stop handing the model the catalog. The MCP server exposes three meta-tools, and everything else sits behind them. CAPT names them get_tools_for_tags, get_tool_info and exec_tool. Solarpunk solved the same problem with retrieval before invocation: for each plan step, the agent searched the registry and retrieved only the applicable tool definitions before invoking anything. The planner worked against the shape of the task and was never handed a list of a hundred tools.

This figure is a framework. It shows the call order and what each meta-tool returns, not a benchmark of any implementation. The dashed arrows are reads against the catalog, and only the execute call runs the policy check, since only execution can change anything.

Search takes the agent's description of the task and optional tags, and returns a short ranked list of names with one-line purposes. It does not return schemas. If search returns full contracts for twenty candidates, you have rebuilt the long tool list one call later, and the model is again choosing among competing definitions. We rank on tags for function and on the purpose text for intent, because tags alone miss a task phrased in words the author did not anticipate.

Get schema returns one contract: inputs, allowed values, preconditions, and the target system. The agent reads it, gathers what it needs, and only then commits. Keeping this call separate costs a round trip and buys a decision point, since the agent can read the contract, see that the precondition fails, and choose a different playbook without having executed anything.

Execute validates the inputs against the schema on the server, checks the caller's authority for this action, and runs the steps. It rejects unknown names and inputs outside the schema, and it never trusts the agent's own claim that validation passed. The CAPT post describes the trade as a few extra seconds of discovery for simplicity and scale. We accept the extra calls, because the small context they buy keeps tool selection accurate.

Discovery and authority have to stay separate. An agent that can find the production rollback playbook has not been authorized to run it. The permission boundary applies at the execute call, and the search results should not quietly filter by permission as a substitute for that check. If they do, a misconfigured filter becomes an access decision made somewhere nobody reviews.

Where should playbooks live: central or in the repo?

Some procedures apply across the company, like debugging patterns, data analysis flows and review helpers. Others belong to one service, such as how this team rotates this key or backfills this table. Forcing both into one central repository creates a queue in front of the platform team and a pile of playbooks nobody outside one team can review. Keeping everything local means every team rewrites the shared ones, slightly differently.

CAPT runs both kinds, with central playbooks for company-wide workflows and local playbooks inside each repository, discovered together when the server starts. That matches what we would design, and the part worth specifying is the merge.

	Central playbooks	Repo-local playbooks
Scope	Workflows that cross teams and repositories	One service, one team, one codebase
Where they live	A shared repository with its own review	The service repository, next to the code they act on
Who reviews a change	The platform team that owns the defaults	The service team, in the same pull request as the code
Typical examples	Incident triage, experiment cleanup, pre-review checks	This service's backfill, this team's release checklist
Failure if this is the only kind	A queue in front of one team, and stale domain detail	Every team rewrites the shared workflows

This figure is a framework. The merge rules are the design we recommend, and they are not taken from any published implementation.

Build the catalog at session start from both sources and present one catalog. When a local playbook has the same name as a central one, let the repo copy win inside its own repository, because the service team knows its exceptions.

Let the platform team mark a central playbook as required when shadowing it would be unsafe, such as a deploy or a data deletion path. Put the source and the version into every search result and every run record. A reviewer can then tell which copy ran without reconstructing the session.

Local playbooks change with the code, so review them in the same pull request. A playbook that describes last quarter's deploy steps is worse than none, because the agent will follow it confidently. Keeping the playbook next to the code it drives is the most reliable way we know to keep the two in step.

What should every playbook run record?

Once playbooks are tools, every run is an invocation you can log, and that log answers questions a prompt never could. Record one entry per run, linked to the tool calls inside it:

the playbook name, version and source;
the repository and the task it ran against;
the principal the agent acted for;
the validated inputs;
each tool call, with its result status;
the stop reason, whether completed, escalated or failed a precondition;
the verification result, read independently.

That record feeds three decisions. Runs that often stop at the same step point at a playbook that needs a better precondition or a missing tool. Searches that return nothing, or return a playbook the agent then abandons, point at a workflow nobody has written yet. Playbooks that nobody finds are candidates for a better purpose line or for deletion. The CAPT team describes instrumenting every tool and playbook call from the start and using the dashboards to choose what to build next, which is the same loop.

Read the log alongside a small eval set for the catalog itself. For each playbook, keep a few tasks where it should be chosen and a few near-misses where it should not, and check that search ranks it correctly as the catalog grows. A new playbook with a broad purpose line can pull tasks away from an older, correct one, and without these evals you find out from a failed run.

Our evals guide covers how to build that set, and the run records are where its cases come from. The observability you already run for services is the right home for the records, so they sit next to the traces of the systems the playbooks touch.

How do you start?

Start with workflows where the knowledge sits with one or two people and the task recurs. Those give a new playbook the most room to help, and the people who know the procedure can review the first draft in an afternoon.

Pick one workflow that recurs and that only a few people can do well. Write the playbook from the last real run, not from the runbook, because the runbook is usually out of date.
Fill every field in the table above, especially the near-misses in the purpose and the stop conditions. An empty field is a decision the agent will make at run time.
Put the playbook behind the three meta-tools from the first day, even with only a handful. Retrofitting discovery onto a catalog that agents already call by name means changing every caller.
Add the run record before the second playbook ships. Without it you cannot tell which playbook helped, and the next choice is a guess.
Write selection evals for each playbook as you add it: tasks that should find it, and near-misses that should not.
Let service teams add repo-local playbooks once the first central ones are stable, and publish the merge rules before the first name clash.

If the workflows you want to encode also write to production systems, settle the permission model in parallel. Our guide on rolling out agent autonomy covers how an action earns more authority over time, and a playbook is a good unit to promote. We build this layer for clients as part of our MCP servers work, and the agent orchestration work covers the planning loop that calls it.

Questions buyers ask

What is an agent playbook?#

An agent playbook is a written procedure with a contract: a name and tags so it can be found, typed inputs and preconditions so it can be called safely, ordered steps that name the tools to use, and stop conditions and a verification check so the agent knows when it is finished. Exposed through MCP as a tool, it gives an agent a team's real way of doing a task instead of a guess at it.

How is a playbook different from a system prompt or a rules file?#

A system prompt or rules file is loaded on every request and can only describe what to do. A playbook is loaded only when the agent searches for it, has a schema that validates inputs before anything runs, can be executed and chained like any other tool, and leaves a run record. Prompts grow until they crowd the context window, while a catalog of playbooks can grow without the agent seeing more than three meta-tools.

How many tools can an agent hold before it needs discovery?#

There is no fixed number, and it depends on the model and how similar the tools are. On our Solarpunk build, direct tool calling degraded somewhere around thirty tools, when the model began picking plausible tools from the wrong system. LinkedIn's engineering team reports that most MCP clients work best with a few dozen tools at a time. Plan for discovery before you reach that range, because retrofitting it means changing every caller.

Do meta-tools make the agent slower?#

Each task adds a search call and a schema call before execution, so there are extra round trips. In exchange, the context stays small and the model chooses among a few relevant candidates instead of a long list of competing definitions. We accept the extra calls because a wrong tool choice costs far more time than a discovery step, and it often goes unnoticed until someone checks the result.

Who should own the playbooks?#

Central playbooks for cross-team workflows belong to a platform team that reviews them as shared defaults. Repo-local playbooks belong to the service team and should be reviewed in the same pull request as the code they act on, so they change together. Every playbook needs a named owner and a version, and the run record should name the source and version that ran.

Does discovery change what the agent is allowed to do?#

No. Finding a playbook grants nothing. The execute call checks the caller's authority for that specific action before the first step runs, and the permission policy lives there. Search results should not quietly filter by permission as a substitute for that check, because a misconfigured filter then becomes an access decision that nobody reviews.