Grants.gov Scraper: Federal Grants, NIH & NSF Awards API

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

Annotations already supply readOnly/openWorld/non-destructive, and the description goes well beyond them: per-result pricing ($0.003 per grant), the $0.50 default charge cap, the warning that run_max_items does not limit Actor billing while run_max_charge_usd does, typical 5-15s latency with a 300s ceiling, and the JSON {actor, count, items} envelope. These are exactly the operational facts an agent cannot infer from structured fields.

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?

Long but front-loaded: purpose, sibling differentiation, parameter guidance, then a clearly separated 'Behavior' block for cost and timing. The per-item return field list and a few parameter notes slightly duplicate the schema, but nothing is filler given the 17-parameter surface.

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?

With 17 parameters and no output schema, the description still covers return shape (enumerated fields plus the {actor, count, items} envelope), cost model, spending cap, and timeout recovery advice. An agent has everything needed to call it correctly and to budget the run.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: sources is framed as 'apply-able funding vs past awards,' the worst-case billed row count is explained as maxResultsPerSource x number of sources, minAmount is flagged as silently dropping rows whose source publishes no amount, and includeGrantsGovDetails is presented as a speed/detail tradeoff. Some restatement of schema text keeps it from a 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?

States a specific verb and resource ('Search US federal funding') and enumerates the three underlying data sets (Grants.gov opportunities, NIH RePORTER, NSF awards) in the first sentence. It explicitly names and contrasts two siblings, sbir_sttr_topic_radar and federal_contract_finder, 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?

Gives positive when-to-use ('you need grants to apply for or want to see who was funded for a topic') and explicit when-not-to-use with named alternatives for both contract search and SBIR/STTR topics. The routing between the three tools is unambiguous.

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