Discover Offices

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context beyond that: it returns specific fields (code, name, total obligations, competition rate, set-aside share), notes that office_code is its own namespace with no shared identifier links, and mentions it is free on every plan. There is no contradiction with the annotations.

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 core purpose, followed by compact bullet-style parameter explanations. Every sentence adds value: usage rationale, parameter semantics, return fields, sibling routing, and namespace caveat. There is no filler or tautology.

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 output schema exists and annotations cover read-only/idempotent behavior, the description still provides everything needed to call the tool correctly: required parameter format, sort options, limit cap, expected return fields, and explicit guidance on when to move to get_office_profile. No important operational detail is missing.

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, and it succeeds. It explains that naics is a 2-6 digit code and required, defines each sort value ('biggest' means total obligations, 'most_open' means highest full-and-open share, 'most_setaside' means highest set-aside share), and sets a maximum limit of 100.

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: 'Find which contracting offices buy a NAICS code, ranked, each with its own win-facts.' It clearly distinguishes this tool from get_office_profile by noting that discover_offices focuses on one NAICS, while get_office_profile covers all NAICS for an office.

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 explicit when-to-use guidance: it is a Market Research tool that answers 'who actually buys this, not just which department,' and explains why office-level ranking matters over department-wide averages. It also names the alternative get_office_profile and states the condition for switching to it.

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