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

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world read, so the safety profile is covered; the description adds genuinely new behavior. It discloses that the connector has no access to the user's cloud accounts and that runbooks merely supply a detection query the user runs themselves, which is a critical expectation-setting detail. It also documents the success payload shape, the miss behavior with up to three string-distance suggestions for self-correction, and the optional MCP Apps rendering path.

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?

It is front-loaded with purpose and usage before the Args/Returns blocks, so an agent can decide quickly. The Args and Returns sections duplicate some information already conveyed by the schema and output schema, and the MCP Apps rendering note is marginally useful, but nothing is genuinely wasteful.

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 one-parameter read tool, the description covers purpose, selection criteria, parameter format and provenance, success payload, failure payload with recovery hints, and the no-account-access constraint. Despite an output schema existing, the explicit miss-with-suggestions behavior is worth stating and closes the only real ambiguity an agent would face.

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 0%, so the description carries the full burden for the single required parameter, and it does: it defines the argument as a playbook slug sourced from list_playbooks and supplies three concrete example values across AWS, Azure, and cross-cloud patterns. That is more meaning than the bare string type in the schema.

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 names a specific verb ("Fetch") and a precisely scoped resource ("the step-by-step runbook for one specific waste pattern") and enumerates the contents: symptoms, detection queries, the fix, and the anti-pattern. It is clearly distinguishable from siblings like list_playbooks and find_playbooks, which operate on collections rather than a single named runbook.

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 states exactly when to reach for this tool: the user asks how to detect, confirm, or fix one specific named waste pattern, with concrete examples (zombie NAT gateway, snapshot sprawl, idle SageMaker endpoint). It also covers the ambiguous case of "which of my X..." questions and implicitly routes slug discovery to list_playbooks, leaving little to infer.

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