Lookup Agency

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavior beyond those: results are grouped by canonical name, `suggested_filter_value` may be broader than a single component, and `raw_variations` can be used for narrower filtering. This meaningfully clarifies output semantics, though it does not discuss edge cases such as zero matches.

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 front-loaded with the core purpose, then provides usage context, a critical exception, and output-usage nuance. Each sentence adds distinct value, and the structure moves from 'what' to 'when' to 'how to interpret results' without unnecessary filler.

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 lookup tool with read-only annotations and an output schema, the description covers the main gaps: what the query should contain, where the result is meant to be used, where it is not applicable, and how to interpret the suggested filter value. Nothing essential is missing for correct usage.

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 schema provides no description for the single `query` parameter, but the description fully compensates by specifying accepted forms: acronyms (FEMA, DoD, NASA), partial names, or full agency names. This is exactly the semantic content needed to invoke the tool correctly.

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: 'Resolve an agency acronym or partial name to canonical SAM.gov agency strings.' It clearly distinguishes the tool from sibling search tools by explaining its role as a name-resolution helper for the `agency` filter rather than a direct data search tool.

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 explicitly tells when to use this tool: to find the correct `agency` filter substring for search_opportunities, search_companies, and most other tools. It also gives a clear exclusion, noting that search_forecasts uses different natural-language agency names and that this tool's suggestions will not match there.

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