Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this read-only, idempotent, and non-destructive. The description adds meaningful behavioral expectations beyond that: it returns operator_brief and deep_link, and instructs the agent to 'Always speak those; never cite this Play by id alone.' This is valuable output-handling context not present in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and is organized into a useful routing note. However, it repeats the same instruction twice: 'never cite this Play by id alone' and 'Speak operator_brief + deep_link' appear in both the opening paragraph and the routing paragraph. This redundancy makes it less concise than it could be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description reasonably compensates by naming the return fields (operator_brief, deep_link) and the expected presentation behavior. It also clarifies what a Playbook contains and where this fits in the workflow. Some domain-specific terms are dense, but an agent operating in this system likely has enough context to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description mentions lookup 'by id or title', but the schema already documents playbook_id as a UUID and playbook_title as a title or fragment. The description does not add meaningful parameter-level detail beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Read ONE Playbook by id or title', a specific verb, resource, and selection mechanism. It also differentiates from list_playbooks by calling it 'the index' and positions itself relative to agree_playbook and run_playbook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit routing: 'Use before agree_playbook / run_playbook' and states that list_playbooks is the index. The 'Routing' sentence provides a clear decision rule: inspect one Playbook's steps and Agree status, then use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.