USAspending Scraper: Federal Contract Awards & Recompete Finder

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, yet the description adds substantial context beyond them: per-contract pricing ($0.002), a hard per-call cap via run_max_charge_usd, the fact that empty runs aren't billed, that run_max_items also constrains billing, that raising maxResults can bill more than is returned, and 5-15s typical latency with a 300s timeout ceiling. The one gap is that it doesn't explain why idempotentHint is false (e.g. that each call creates a fresh Actor run on the user's Apify account), which is the behavior an agent is most likely to get wrong on retries.

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 text is front-loaded with purpose, then differentiation, then per-mode parameter behavior, then operational/cost behavior — a sensible information hierarchy with no filler sentences. It is nonetheless long for a description, and the middle "Parameters:" passage repeats several facts the 100%-covered schema already states.

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 19-parameter tool with no output schema, the description stays complete: it enumerates the per-item return fields (agentSummary, awardId, recipientUei, monthsLeft, status, url, etc.), the top-level response envelope {actor, count, items}, cost and timeout guardrails, and the empty-result case. An agent has everything needed to call this correctly and interpret the result.

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 100%, so the baseline is 3; the description earns a lift by documenting cross-parameter interactions the schema does not fully surface — that mode=recompete ignores sortBy, sorts by soonest end date and uses recompeteMonths as its window, and that run_max_items back-fills maxResults when it is unset. Other parameter notes (NAICS prefixes, UEI support in recipientNames, 3-character keyword minimum) restate what the schema already says, so it is not a full 5.

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 verb and resource (find US federal prime contract awards on USAspending.gov) and enumerates the filterable dimensions. It immediately distinguishes itself from grants_finder and sbir_strtr_topic_radar by naming both and stating what each covers, so an agent can disambiguate without opening any schema.

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 explicit positive use cases (incumbents, competitor contract history, market sizing by NAICS/agency, recompete pipeline leads) and explicit exclusions with named alternatives ("Do not use for grants… use grants_finder", "not open solicitations… USAspending holds awards, not SAM.gov notices"). The when-to-use/when-not matrix is complete.

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