list_agencies

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral transparency by explaining the summary_only parameter's effect on response size and content, including how child agency references are merged in summary mode. This goes beyond the annotations, providing users with critical knowledge about response behavior and payload size, which is entirely consistent with the read-only annotation.

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 well-structured and front-loaded with the main purpose, then explains the parameter and use case. Every sentence earns its place: purpose, output, usage example, and parameter details. It is detailed without being verbose, covering all necessary information in a concise, readable format.

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 the tool's simplicity (one optional boolean parameter), the presence of an output schema, and read-only annotations, the description is complete. It states what the tool returns (agency names, slugs, chapter references) and explains the sole parameter's behavior. No critical gaps remain; the output schema covers return structure, and the description covers all un-schema'd semantics.

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?

The single parameter summary_only has zero description coverage in the schema, but the tool description thoroughly explains its semantics: 'summary_only (default True) strips the 'children' and most of 'cfr_references' to keep the response compact (~20 KB vs ~100 KB)' and details the merging behavior. This fully compensates for the schema's lack of description, giving the agent precise understanding of the parameter's effect.

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 clearly states the tool's purpose: 'List all agencies with their CFR title and chapter references.' This uses a specific verb (List) and resource (agencies), and specifies the output (agency names, slugs, and chapter references). It uniquely distinguishes itself from sibling tools that focus on sections, content, or corrections, making its purpose unambiguous.

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 provides a clear use case: 'Useful for finding which chapter corresponds to an agency's FAR supplement.' This gives concrete guidance on when to use the tool. However, it does not explicitly mention when not to use it or reference alternative tools. Since it's a simple listing tool and siblings are clearly different, the guidance is adequate but not exhaustive.

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