MCP prompts vs tools for agent playbooks

MCP prompts are templates a server offers for a person to pick, often as a slash command, and the client fetches one with prompts/get and puts the returned messages into the conversation. A workflow an agent should find and run on its own belongs in the other primitive: write it as a playbook with a typed contract and expose it as a tool.

Key facts

Definition

MCP prompts are templates a server offers for a person to pick, while a playbook an agent finds and runs on its own is a recurring workflow with a typed contract, exposed through MCP as a tool.

How Bigcircle does it

Bigcircle recommends an MCP prompt for a workflow a person starts by name, and a tool for one the agent should choose, because only a tool's inputs are checked against a schema before it runs.
Bigcircle recommends three meta-tools in front of the playbook catalog: one searches it, one returns a single playbook's schema, and one executes a playbook with validated inputs.
On Solarpunk, Bigcircle stopped handing the model the full tool registry after selection went wrong at roughly thirty tools, and each plan step searched the registry instead.

Comparison

Putting every playbook in context as its own tool makes the model choose among competing definitions, while the catalog keeps the context to search, schema and execute.

Put three small meta-tools in front of the catalog, one to search it, one to return a playbook's schema, and one to execute 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 missing piece is rarely capability. A current model can write the migration, read the stack trace and draft the pull request. 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 run in which order, and which check a reviewer will block on. In most engineering teams that knowledge 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, what MCP prompts are and why an agent's playbook should be a tool rather than a prompt, and how three meta-tools keep a large catalog usable under the stateless MCP specification of 28 July 2026. It then covers how central and repo-local playbooks share one catalog, what each run should record, and when you need none of it. Who may run a playbook, and with which credential, has its own guide: AI agent permissions.

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.

A better model does not close that gap, because the agent lacks the organization's context rather than capability. LinkedIn's CAPT framework for its coding agents, described in January 2026, runs a design close to the one below on MCP, and we point to it where it made a choice worth copying or left one open.

We met the tool side of that problem on Solarpunk, an agent that works across a leader's email, calendar, documents, CRM and ERP. With every tool described in the prompt, selection held up until roughly thirty tools. Past that, the model picked plausible tools from the wrong system and returned confident results, and nothing in the output showed it.

The fix was to stop handing the model the registry. The planner breaks the goal into steps first, and each step searches the registry for the few contracts that apply, which kept selection reliable past a hundred tools. The model never sees the full list. It chooses among a handful of contracts picked for the step in hand, rather than among a hundred competing ones.

Those two findings point at one design. Write the procedure down so the agent does not have to guess it, and keep the catalog of procedures out of the context window until a task needs one. A playbook handles the first half and the meta-tools handle the second, so the 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 tool each step calls, and the conditions under which it stops. Start from the runbooks and onboarding documents you already have. The work is turning prose a person interprets into fields an agent cannot misread, and each field below has a failure that shows up when it is left empty.

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

Spend the most time on the purpose field, and 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. A purpose line that only lists what the playbook does gives the agent no way to rule it out.

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

Hand-written runbooks are thinnest in the last group. A person following a runbook notices when something looks wrong and stops. An agent following one keeps going unless the document spells out what wrong looks like, so write each stop condition as a state the agent can observe, such as "the flag still has live traffic."

Make verification read the result from a different path than the one that made the change. We built Solarpunk to compare the agent's claim of completion against the actual state of the target application, because only that comparison catches an agent reporting success on work that was never finished. A playbook whose last step is "confirm the API returned 200" has asked the change to grade itself. Read AI agent verification for that failure in full.

What are MCP prompts?

An MCP server can offer a client three kinds of feature: tools, resources and prompts, and prompts are the kind built for a person to choose. The 2026-07-28 specification calls them user-controlled: a server lists templates through prompts/list, a user picks one, and the client calls prompts/get with the template's name and arguments. The server returns messages, in the user and assistant roles, which the client adds to the conversation.

Use a prompt for a procedure a person starts on purpose, such as a release checklist an engineer runs by name from the editor. The person has already chosen the workflow, and the template supplies the steps and asks for the arguments it needs. Validate those arguments on the server, as the specification asks, because the returned messages go straight into the model's context. Filter prompts/list by the caller's authorization the same way you would filter tools/list, which the specification allows for both.

Do not use a prompt for a procedure the agent should find on its own. Tools are the model-controlled kind, which the model discovers and calls without a person choosing, and prompts were not designed for that. A prompt's arguments carry a name and a required flag but no type, and the server sees the prompts/get request and nothing after it. The steps then run as whatever tool calls the model decides to make, so none of them is checked against the playbook.

Should a playbook be an MCP prompt or a tool?

We put a playbook behind a tool whenever an agent, not a person, decides when it runs. Teams usually try other homes for procedure first, 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. An MCP prompt works for the person who picks it and is invisible to an agent working alone.

The table compares those options on the properties that matter once agents run them every day:

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
MCP prompt	When a person selects it	No, it returns messages to follow	Yes, on the server	For a menu a person reads, but the agent does not choose from it
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, and the agent can decide when to call it and chain it with other tools. A prompt can do none of that, and it cannot be logged as an invocation, because nothing was invoked. CAPT made the same move: each playbook is exposed to agents as a tool rather than as a prompt template.

Type the inputs for a second reason too. 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, validation fails at the door, which is a much better place to fail than step four of a cleanup.

We built Solarpunk's tool layer this way, with every tool a typed contract with declared inputs, outputs and side effects, so the set of registered contracts is everything the agent can do. A playbook is one more contract in that set, and it can be governed like any other tool, with the same checks and the same log.

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. Do not answer it with namespaces. Grouping tools by workflow looks like the fix and moves the work onto engineers: LinkedIn grouped CAPT's tools into namespaces first, such as data and on-call, and engineers then had to manage namespaces to keep their agents usable. Put three meta-tools on the MCP server instead and keep everything else behind them, as CAPT now does with get_tools_for_tags, get_tool_info and exec_tool.

The dashed arrows are reads against the catalog. Only the execute call runs a policy check, because 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. 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 see that a 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 cost is a round trip or two per task, which LinkedIn puts at a few extra seconds, and it is worth paying every time, because a wrong pick on Solarpunk produced a confident answer from the wrong system, which costs more to find than two round trips cost to make.

The current specification changes how these calls relate to each other. As of the 28 July 2026 revision, MCP has no protocol session and no initialize handshake, and every request carries its own protocol version and credentials. A run that spans a schema call, an execute call and a later status check cannot lean on connection state to tie them together.

The specification's guidance is an explicit handle, an opaque ID that the server creates and the agent passes back as an ordinary argument, with the caller's authorization checked against it on every call. Return a run ID from execute and require it on anything that follows. A status check from a different client, or from the same agent after a restart, is then checked against the same authority as the run that created it.

Discovery and authority have to stay separate. An agent that can find the production rollback playbook has not been authorized to run it. The same revision lets a server vary tools/list by the authorization on the request, but with meta-tools that list is three entries long whoever asks. The check that protects production is the one at execute, and MCP authorization covers the token and the refusal it should return.

Search results should not filter by permission as a substitute for that check. If they do, a misconfigured filter becomes an access decision made somewhere nobody reviews. A playbook the agent should have been refused never appears, so the refusal is never logged either.

Where should playbooks live: central or repo-local?

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. Central playbooks cover company-wide workflows, local playbooks live inside each repository, and the server discovers both when it starts and presents them to the agent as one catalog. What happens when the two collide is the part worth specifying.

	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

The merge rules in the figure are the design we recommend.

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 where 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, so a reviewer can tell which copy ran without reconstructing the run.

Review local playbooks in the same pull request as the code they drive. A playbook still listing last quarter's deploy steps is worse than none, because the agent will follow it confidently. If the playbook sits in another repository, the engineer changing the deploy never sees it, and the two drift apart without anyone deciding they should.

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. Log from the first day rather than after the first bad run. CAPT recorded the time, the repository, the outcome and the tool or playbook for every call from the start, and those fields are the minimum. 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 person or service the agent acted for;
the run ID and 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.

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 still 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. The three meta-tools and each playbook's schema can also be pinned on every pull request with no model attached, and MCP server testing covers how.

Our evals guide covers how to build that set, and the run records are where its cases come from. A run that stopped on a precondition, or that a reviewer reverted, can go into the set as a case the same day.

When should you skip the catalog?

Meta-tools add a search call and a schema call to every task, and a catalog needs an owner. If the agent's whole tool list is a dozen tools from one system, give it the tools directly and put the procedure into their descriptions. A catalog is worth its upkeep when the procedures outnumber what fits in a tool list, or when more than one team writes them.

Do not write a playbook for work whose steps change every week. The playbook goes stale faster than anyone updates it, and the agent follows a stale playbook as confidently as a current one.

Start with a workflow that recurs, that only one or two people do well, and whose owners can review a first draft in an afternoon. Write it from the last real run rather than from the runbook, which is usually out of date, and ask the person who ran it to mark the steps they skipped or reordered. Put it behind the three meta-tools from the first day, since adding discovery to a catalog that agents already call by name means changing every caller.

If the workflows write to production systems, settle the permission model before the first one ships. AI agent governance covers how an action earns more authority over time, and a playbook is a convenient unit to promote. The tools a playbook calls are shaped in how to design MCP tools, and keeping definitions the same across every agent that runs one is covered in shared business context for every AI agent. Bigcircle's MCP servers work covers this layer.

Common questions

What are MCP prompts?#

MCP prompts are reusable templates a server offers to a client for a person to choose, often shown as slash commands. The client lists them with prompts/list, and when the user picks one it calls prompts/get with the template's arguments. The server returns messages that the client adds to the conversation. The 2026-07-28 specification calls prompts user-controlled, meaning a person decides when one is used.

What is the difference between MCP prompts and tools?#

A prompt is chosen by a person and returns messages for the model to follow. A tool is chosen by the model and runs on the server, with its inputs checked against a JSON Schema before anything happens. Use a prompt for a workflow someone starts by name. Use a tool for one the agent should find and run on its own, since the server can then validate, authorize and log each run.

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 alike the tools are. On Bigcircle's Solarpunk build, direct tool calling degraded at roughly thirty tools, when the model began picking plausible tools from the wrong system. Plan for discovery before you reach that range, because adding it later 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. A wrong tool choice usually costs more than the extra calls, because it tends to go unnoticed until someone checks the result.

Does the 2026 MCP specification change how meta-tools work?#

The 28 July 2026 revision removed protocol sessions and the initialize handshake, so every request stands alone and carries its own credentials. Search, get schema and execute still work as three ordinary tool calls. A playbook run that spans several calls needs an explicit run ID, returned by the server and passed back as an argument, with the caller's authorization checked on each call.

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 filter by permission as a substitute for that check, because a misconfigured filter then becomes an access decision that nobody reviews.