> For the complete documentation index, see [llms.txt](https://help.filed.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.filed.com/reference/playbook/creating-protocols.md).

# Creating protocols

## How protocols are created

Protocols are authored through the Chat assistant, not through a standalone form. You describe a preference or rule in plain language - "whenever you're doing tax prep, always check..." or "remember to..." - and the assistant proposes a structured protocol based on what you said. Chat is the authoring surface by design, so the protocol body stays grounded in the natural language you actually use to describe your firm's preferences.

Once the assistant proposes a protocol, you review it, refine it through conversation if needed, and approve it. Approval writes the protocol immediately to your personal Playbook list, where it becomes active right away. Chat can only create personal ("Yours") protocols; promoting a protocol to firm scope is a separate admin-gated step.

## Step 1 - express your intent in Chat

**Walkthrough: express a protocol intent in Chat**

1. Open a Chat session (from a client's Chat tab, or any Chat surface) and type a protocol-triggering phrase in plain language - "remember to...", "whenever you do tax prep...", or "always check...". For example: "Remember to always verify Box 1 wages against the prior-year return before completing tax prep."
2. The assistant recognizes the intent, confirms the rule it heard, and asks any clarifying questions it needs (for example, which return types it applies to and whether there is a variance threshold) before drafting a protocol.

![The assistant recognizing a protocol intent and asking clarifying questions](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image1.webp)

## Step 2 - review the proposed protocol

**Walkthrough: review the proposed protocol**

Once you have answered the assistant's questions, it drafts the protocol and opens a proposal panel. The panel shows the full protocol for review: the auto-generated kebab-case **name**, the **description** (the trigger that decides when the protocol applies), and the **body** (the full instruction, including purpose, when it applies, what to do, examples, and when not to apply). A **Save protocol** and **Discard** action sit at the bottom.

![The proposal panel showing the protocol name, description, and full body](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image2.webp)

To refine before saving, keep chatting - tell the assistant what to change ("only apply this to 1040 returns", "raise the threshold to 15%") and it revises the proposal in place under the same name. Save only once the description and body read the way you want.

### The description field (trigger)

The description is what the system evaluates to decide whether a protocol applies to the current run. It also appears as the one-line label in the Playbook list, so it is the first thing you and your colleagues see when scanning your protocol library.

A good description is specific enough that the protocol does not activate in situations it was not designed for: "During tax prep when a Schedule C is present" is more reliable than "during tax prep." The description is required, with a maximum length of 1,024 characters.

### The body field (instruction)

The body is the full instruction the assistant follows when the protocol is active. It supports Markdown, so you can use bullet lists, numbered steps, conditions, and emphasis to make the rule clear. The assistant reads the body cold, with no prior context about why the rule exists, so it should be self-contained and actionable on its own.

The body is required, with a maximum size of 8,000 bytes and 500 lines.

## Step 3 - approve and save

**Walkthrough: approve and save the protocol**

1. Click **Save protocol** on the proposal panel. The assistant confirms in the conversation - the proposal card collapses to a compact "Saved to your protocols" card with the protocol name, and the assistant restates the rule it will now follow.

![The assistant confirming the protocol was saved to your protocols](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image3.webp)

2. Open **Playbook** from the left sidebar and select the matching task type (here, **AI Tax Prep**). The new protocol appears in the **Yours** section with an **Active** status badge, meaning it runs immediately on your future task sessions of that type.

![The saved protocol in the Yours section of Playbook with an Active badge](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image4.webp)

## Choosing the right task type

When the assistant proposes a protocol, it infers the intended task type from your conversation. If you are in an AI Tax Prep session and say "always check for a Schedule C before proceeding," the assistant assigns the protocol to AI Tax Prep. If it guesses incorrectly, you can correct it during the review step before approving.

Protocols are task-type-specific. A protocol saved under AI Tax Prep will not run during AI Review, AI Tax Planning, Binder, or Chat sessions, and vice versa. The five task types are AI Tax Prep, AI Review, AI Tax Planning, Binder, and Chat. If a rule genuinely applies to more than one task type, create a separate protocol for each.

## Editing a protocol after creation

**Walkthrough: edit a protocol after creation**

Protocols are edited through the Chat assistant. In any Chat, name the protocol and describe the change ("update my missing-docs-check protocol to also flag prior-year carryovers"). The assistant revises the protocol and re-proposes it with the same name, so approving the revision updates it in place rather than creating a duplicate. The updated protocol then reflects the change in the Playbook list.

## Toggling a protocol for a single run

Disabling (below) is a persistent, Playbook-level change. To skip a protocol for just one run without disabling it going forward, see [Turning protocols on or off for a specific prep](/reference/playbook/toggling-protocols-per-run.md).

## Enabling and disabling a protocol

All new protocols are active when they are first saved. A disabled protocol remains visible in the Playbook list but is skipped at run time, so it is not injected into the assistant's context. Disabling lets you suspend a protocol temporarily without deleting it.

**Walkthrough: manage a protocol from the list**

Select a protocol's checkbox in the Playbook list to reveal its actions. From here you can **Share with firm** (personal protocols) and, from the **More actions** menu, **Delete** the protocol. Firm protocols are managed by admins from the **Firm's** section (where the actions are **Approve** and **Deny** for pending items). To temporarily change a protocol's behavior without deleting it, edit it through Chat (see above) so it no longer matches the situations you want to skip.

## Naming conventions and limits

Protocol names are auto-generated in kebab-case by the Chat assistant when it proposes the protocol. You can change the name during the review step before approving.

Key constraints:

* **Name**: kebab-case only (lowercase letters, numbers, and hyphens). Maximum 64 characters. Must be unique within the same task type and scope (personal or firm). Reserved names used by Filed's built-in Chat tools cannot be used.
* **Description**: Required. Maximum 1,024 characters. No control characters.
* **Body**: Required. Maximum 8,000 bytes. Maximum 500 lines.

## More worked examples

A protocol is meant to encode a rule your best preparers or reviewers already apply from experience, expressed once so the whole team benefits from it. Two more examples, beyond the Box 1 wages check in Step 1:

**A threshold on Form 1116 (foreign tax credit).** "When a client has foreign tax credit and the amount on Form 1116 is below $600 for a single filer or $1,200 for married filing jointly, check whether the simplified limitation election (no Form 1116 required) applies instead, and note the reasoning in Pre-Entry Notes." This encodes a judgment call - when the simpler path is available - that would otherwise depend on an individual preparer remembering the de minimis threshold.

**An HSA distribution check.** "Whenever a client has HSA distributions reported on Form 1099-SA, confirm that qualified medical expense documentation is present in the binder before marking the distribution as non-taxable. If documentation is missing, flag it in Pre-Entry Notes as a required follow-up." This turns a firm's due-diligence standard on HSA distributions into a rule Filed applies automatically on every return that has one, rather than relying on each preparer to remember to check.

Both examples follow the same shape as any protocol: a specific trigger (the description) and a self-contained instruction (the body) that does not assume the assistant remembers anything about the client beyond what is in the current binder.

## Tips for writing effective protocols

**Be specific in the description.** The description is evaluated at run time to decide whether the protocol applies. Vague triggers like "during tax prep" can fire in situations where they are not relevant. Triggers like "when a Schedule C is present" or "when the client has K-1 income from a partnership" activate the protocol precisely when you need it.

**Write the body as if the assistant has never seen this client before.** The body is read cold, with no memory of previous sessions or other protocols. If the rule depends on a concept (a form type, a firm policy, a threshold), spell it out rather than assuming the assistant will infer it.

**Avoid duplicating firm protocols.** Before saving a personal protocol, check the Firm's section for the same task type. If a firm protocol already covers the rule, a personal duplicate adds overhead without changing behavior (byte-identical pairs are de-duplicated automatically). To override a firm rule for your own runs, write a personal protocol with the same name and a different body; your version takes precedence.

**Keep each protocol focused.** A protocol covering one specific job is easier to maintain, reason about, and update than one that bundles five unrelated rules. If a body is growing very long, consider splitting it into two protocols with more targeted descriptions.

**Use the Chat assistant to iterate.** You do not need to get the protocol right on the first proposal. Describe what is wrong, and the assistant revises and re-proposes with the same name, so the update lands in place rather than creating a duplicate.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.filed.com/reference/playbook/creating-protocols.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.