playbook

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

With no annotations, the description carries the full burden. It discloses a key behavioral trait: when the symptom is unknown, it falls back and reports with fell_back=true. This is valuable and goes beyond simple 'returns steps.' It also implies a read-only operation. However, it does not describe the complete return structure, error handling, or any side effects, though for a read tool this is minor.

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?

Two sentences, no filler. The primary purpose is front-loaded, and the fallback condition is stated concisely with a concrete outcome (fell_back=true). Every word earns its place.

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?

Given two simple parameters and no output schema or annotations, the description provides core information: what it returns conceptually, the fallback condition, and a note about a response field. It omits the exact return payload shape (e.g., list of steps vs. free text), but for a tool this straightforward, it's nearly sufficient. A tiny bit more about the output format would make it a 5.

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 coverage is 50% (only symptom has a description). The description adds meaning by explaining that a missing/unknown symptom triggers fallback behavior, linking symptom to the fallback logic. It clarifies the role of service indirectly via 'service's general steps.' Yet it does not elaborate on allowed values, format, or examples for either parameter beyond what the schema already states for symptom.

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?

States a specific action and resource: retrieving the first checks from a runbook for a service. The description clearly sets it apart from siblings (ownership, escalation, impact) by focusing on runbook guidance. However, 'what the runbook says to check first' is slightly vague about whether it returns a list, a single item, or a message, so it's not a perfect 5.

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 implies usage: use this tool when you need the runbook's first steps, and it handles unknown symptoms by falling back to general steps. It does not explicitly name alternatives or state when not to use it (e.g., if you need escalation path, use escalation_path). The fallback behavior is a form of guidance, but it lacks explicit comparisons to sibling tools.

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