Search Recompetes

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral detail beyond that: it is 'Pro only,' 'factual, never scored,' and explains the date_anchor semantics (current_end vs potential_end) and the options_exhausted_only filter for high-confidence recompetes. It also notes a limitation (get_recompete does not carry agency_code) — transparency that annotations cannot provide.

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 long but every sentence earns its place: it front-loads the core purpose, then uses a compact bullet-style parameter list, then explains return fields and a caveat. The structure is efficient for the tool's complexity, though it could trim a few redundant phrases (e.g., 'Capture & Teaming / Post-Award tool' could be merged). It remains appropriately sized for a 14-parameter tool.

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 complexity (14 filterable parameters, domain-specific behavior, and an output schema), the description is remarkably complete. It covers all critical filters, explains the date window semantics, clarifies the difference between the two date anchors, and tells the agent which fields to pass to which follow-up tools. It does not describe the `state`, `set_aside`, `amount_min/max` parameters, though those are relatively self-explanatory from their names. The existence of an output schema mitigates the need to describe return objects further.

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 0% schema description coverage, the description carries the full burden for parameter meaning. It explains naics (exactly 6 digits), agency (name substring), the ends_after_months/ends_within_months window with an example (0-18 = 'ending in the next 18 months'), date_anchor options, options_exhausted_only, incumbent_excluded (both true and false semantics), and all four sort_by values. It also maps return fields to next-step tools. This goes well beyond the schema and makes the parameters actionable.

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-resource pair ('Find contracts entering recompete within a window') and immediately distinguishes itself from its sibling get_recompete, noting this is the search form while that is the single-contract form. It also clarifies two concrete use cases (market read for new business, and monitoring your own contract's expiration), giving the agent unambiguous purpose.

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 explicitly states when to use this tool over the sibling get_recompete ('see get_recompete for the single-contract form') and describes the two primary contexts (Capture & Teaming / Post-Award). It also mentions it's a 'factual, never scored' read, which sets expectations for what it is not (no win-probability scoring). The pointer to get_recompete is a clear alternative-routing instruction.

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