Anatomy of a playbook

A playbook is a triage profile: this kind of ticket, investigated this way, using these systems. It is the single highest-leverage thing an admin configures, because it is the difference between an agent that wanders and an agent that knows where to look.

For the mechanics of the editor, see Managing playbooks. This page is about what to put in it.

Two consumers, four fields

The fields are read by two different things at two different times, and confusing them is the most common mistake.

So: description and routing hints answer "is this ticket mine?" and triage instructions answer "now that it is mine, what do I do?". Writing investigation procedure into the description makes classification worse and does not help the agent at all.

Description

One or two sentences describing the class of ticket, in the language your customers use, not your internal jargon.

Tickets about money owed to a merchant that has not arrived: payouts, settlement timing, missing transfers, payout account setup.

Avoid writing what you would like to be true ("all payment issues") — the classifier compares tickets against every playbook, and a vague description drags in tickets that belong elsewhere.

Routing hints

The keyword layer. Merchant names, product names, error strings your customers paste, example subject lines.

payout, settlement, transfer, "money not received", "where is my money", bank account, ACH, "payout pending"

This is where you put the phrasings that a semantic description misses — a specific error code, an internal product codename customers have learned.

Triage instructions

The important field, and the only required one. This is a procedure written for someone competent who does not know your systems.

See Writing triage instructions — it is worth its own page.

Data sources

The allowlist of MCP servers the agent may call. Selecting none means all, which is a fine starting point.

Narrowing it makes investigations faster and cheaper and stops the agent drifting into irrelevant systems. It also means a root cause living outside the allowlist becomes unreachable — and the agent will correctly say so rather than inventing something.

Visibility

Organization-wide, or restricted to selected teams. Team scoping governs who can manually use the playbook. It does not govern auto-classification, which considers every enabled playbook in the organization.

How to tell whether a playbook is good

Run the same ticket twice.

1. Scoped to this playbook, and
2. with no playbook at all.

Compare the tool chips and the conclusion.

• Same answer, fewer tool calls → the playbook is doing its job.
• Same answer, same number of calls → the instructions are not adding anything yet.
• Worse answer → the data-source allowlist is too narrow, or the instructions are pointing at the wrong place first.

Then check the routing: filter the inbox by "no playbook" and see which tickets should have matched. Those are your missing routing hints.

Anti-patterns

One giant playbook. If your allowlist is everything and your instructions are "investigate the issue", you have a generic triage with extra steps. Generic triage is already the default for unmatched tickets.

Playbooks that overlap. Two playbooks whose descriptions both plausibly match the same ticket make classification a coin flip. Merge them, or sharpen both descriptions until the boundary is obvious.

Scoping away the answer. A playbook that excludes the system where the root cause actually lives produces confident "could not determine" reports forever. This is why the two-run comparison above matters.

Instructions written for a model rather than a person. "You are an expert support engineer" adds nothing. "Check payout_configs for a row matching the merchant before anything else" adds everything.

The five examples

The following pages are complete, copyable playbooks covering the common support-ops territory. They assume the data sources are named as in the integration catalog; adjust the keys to match your own.