Search Subawards

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

Annotations already signal read-only/idempotent/non-destructive; the description adds materially beyond that: FY2025 data coverage floor, silent clamping of date_from with the response window block disclosing actual range, and absence of cage_code for CAGE cross-checking. These are behavioral surprises an agent would otherwise discover at runtime.

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 organized into purpose, sibling routing, parameter constraints, and data caveats, with important information front-loaded. The bullet list and explicit NOTE make it scannable. The 'Award & Compliance tool' line adds only mild context and could be trimmed, but overall it earns its length.

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 14 optional parameters and zero schema descriptions, the definition covers the most critical constraints and caveats, and an output schema exists for return values. Still, several optional parameters (agency, amount filters, sort/pagination, date formatting) are left undefined, so an agent may still guess at valid inputs. It is adequate and helpful, but not fully complete for a tool this parameter-rich.

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 schema description coverage at 0%, the description carries a heavy burden. It usefully documents prime_uei/sub_uei exact 12-char, piid semantics, naics 6-digit, sub_name substring min 3, and limit max 250. However, agency, amount_min/max, sort_by/order, offset, and date_to still have no explanation in either the schema or description, leaving significant gaps.

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 names a specific action ('Search FFATA subawards') and the unique resource, and the parenthetical 'who primes paid as subcontractors' clarifies the domain. It explicitly names sibling tools with a narrower focus, so the agent can differentiate it from get_prime_subawards/get_prime_relationships without opening schemas.

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 when NOT to use this tool: for single-UEI reverse lookups, use get_prime_subawards/get_prime_relationships, described as narrower and simpler. This implies this tool is for broader cross-prime/sub searches and gives a concrete routing rule. It also provides per-parameter constraints that guide usage.

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