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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine context beyond that: entry size (~90-170 lines), the exact response envelope `{"playbooks": [...], "total": N}`, and the purpose of `approx_tokens` as a pre-fetch budgeting hint. It doesn't mention catalogue scale or pagination, but since all results appear to be returned in one listing, little is missing.

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?

Front-loaded with purpose, then the alternative, then the return shape — a logical order for an agent. The waste-pattern enumeration in the first sentence is somewhat long but earns its place by letting the agent judge coverage; minor redundancy between 'scope (aws/azure/gcp/cross-cloud)' and the provider list above.

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 zero-parameter, read-only catalogue tool with annotations and an output schema, this is complete: it covers what it returns, the field semantics, the sibling split, and the token-budgeting use of approx_tokens. An agent can call it and interpret results without further information.

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?

With zero parameters the baseline is 4; the description correctly signals the tool is unfiltered and redirects filtering intent to find_playbooks rather than implying hidden parameters. It also documents the meaning of each returned field, which goes beyond the input schema's obligations.

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 ('See every ready-made runbook for finding and fixing cloud waste') and enumerates the waste patterns and providers covered, which distinguishes it from the sibling catalog tools (list_references, find_references) and from the retrieval tools (get_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?

It states explicitly when to use this (broad discovery of what runbooks exist) and names `find_playbooks` as the alternative with the exact trigger condition: 'When the question already names a provider, waste category, or confidence tier'. That is a full use/don't-use rule with the sibling named.

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