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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial behavior beyond them: the exact success return shape, the miss behavior returning error plus up to three string-distance suggestions for self-correction, and the optional ui://cloud-finops/playbook-viewer rendering path. This is genuinely useful runtime behavior an agent could not infer from annotations alone.

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?

Despite its length, every sentence earns its place: purpose, content inventory, when-to-use plus a behavioral guardrail, parameter semantics, success/error return formats, and an optional rendering note. The tool's job is front-loaded in the first two sentences, and the rest is organized into clear labeled sections rather than a wall of prose.

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?

For a single-parameter, read-only tool with rich annotations and an existing output schema, the description covers everything needed for correct invocation: what the tool does, what the param means and where it comes from, what a successful call returns, what a miss returns (with self-correction suggestions), and a rendering alternative. There is no meaningful gap an agent would have to guess about.

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 0%, so the description carries the full burden for the 'name' parameter — and it succeeds completely. It defines name as a playbook slug, gives its provenance ('as returned by list_playbooks'), and provides three concrete examples (aws-zombie-nat-gateway, azure-orphan-disks, cross-cloud-untagged-spend-drift). An agent could correctly populate this parameter from the description alone.

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 a specific verb and resource — 'Fetch the step-by-step runbook for one specific waste pattern' — and enumerates the runbook's contents (symptoms, detection queries, fix, anti-pattern). It clearly distinguishes from siblings like list_playbooks by emphasizing 'one specific' named pattern with concrete slug examples, so an agent can route correctly without inspecting schemas.

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?

It explicitly states when to use the tool ('Use this when the user asks how to detect, confirm, or fix one specific named waste pattern') and adds a strong behavioral rule for the user's-own-resources case: fetch the runbook and hand over its detection query, never claim lack of access or ask for data export. It doesn't explicitly name alternatives (e.g., list_playbooks for browsing all runbooks), so it stops short of full when-not guidance.

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