Lookup Agency

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

Annotations already mark the tool readOnly, idempotent, and non-destructive, so the safety profile is handled. The description adds behavioral nuance: results are grouped by canonical name, `suggested_filter_value` can be much broader than one component, and raw_variations can be used for a narrower filter. The search_forecasts exception is also behavioral guidance beyond what annotations convey.

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 covers usage, the exception, parameter semantics, and output nuance. Each section earns its place and there is no filler or redundant repetition of schema or annotations.

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-only lookup with an output schema, the description covers what the input should be, when to use it, when not to use it, and how to interpret the response. There is no missing information an agent needs to select and invoke this tool correctly.

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 input schema only defines `query` as a string with no description, so the description compensates by enumerating accepted inputs: acronyms with examples, partial names, or full agency names. For the single parameter, this is clear enough to construct valid calls without needing additional documentation.

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 opening sentence states a specific verb and resource: 'Resolve an agency acronym or partial name to canonical SAM.gov agency strings.' It then names the downstream consumers and draws an explicit distinction from search_forecasts, so an agent can distinguish this lookup from the many search/get siblings.

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 gives explicit when-to-use guidance: find the right substring for the `agency` filter on search_opportunities, search_companies, or most other tools with an `agency` param. It gives a clear when-not case: search_forecasts uses its own natural-language agency names, so this tool's suggestion will not match there. It also advises using raw_variations when the canonical suggestion is too broad.

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