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

Beyond the annotations (readOnly, openWorld, non-idempotent, non-destructive), it discloses that the tool executes an Apify Actor on the caller's own account, the exact price ($0.002/trial), that zero-result runs are free, the hard spend cap, and the run_max_charge_usd default. It also warns that maxResults set above run_max_items can bill more than is returned, and gives latency expectations and timeout remediation.

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?

Front-loaded with purpose, then differentiation, then usage, then parameters, then a clearly labeled 'Behavior' block — a strong structure for a dense tool. Slightly redundant: the pubmed_evidence_table contrast is stated twice (in the 'Unlike' clause and again in the 'Do not use' clause), and the parameters section reads as one long run-on paragraph.

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 17-parameter, zero-required-parameter, no-output-schema tool, the description covers purpose, alternatives, defaults, billing mechanics, latency, timeout recovery, and a full field inventory of returned items. Nothing an agent needs in order to call it correctly or budget for it appears to be 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 coverage is 100%, so the baseline is 3; the description goes further by explaining that countries/states/city keep trials with at least one matching site and surface matchingSiteCount, and that requireContact filters uncontactable trials before billing. The run_max_items vs maxResults billing interaction is a genuinely non-obvious semantic that the schema text only hints at, though a couple of filter params (keywords, intervention) get no extra treatment.

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?

Opens with a specific verb and resource ('Find clinical trials on the official ClinicalTrials.gov API') and enumerates the filter axes plus returned entities (sponsors, sites, contacts, investigators). It explicitly distinguishes itself from two named alternatives (pubmed_evidence_table for articles, npi_provider_lists for providers), so an agent can classify it without reading the 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 concrete when-to-use cases (recruiting trials near a location, sponsor/site pipelines, investigator and site-contact leads for CROs, suppliers, patient referral) and explicit when-not-to-use routing to pubmed_evidence_table and grants_finder. It also adds per-parameter usage guidance such as 'add COMPLETED etc. for history' and 'updatedWithinDays suits weekly schedules'.

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

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.

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds the economics an agent cannot infer: $0.003 per topic, free runs on zero results, per-call spend cap via run_max_charge_usd ($0.50 default), and the trap that raising maxResults can bill more than is returned. It also discloses latency (5-15 s typical, minutes for crawls), the 300 s timeout ceiling, extra page fetches for includeDetails/includeDodQa, and the {actor, count, items} return envelope — none of which is in 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?

Front-loading is strong: purpose, then sibling differentiation, then exclusions, then parameter tips, then a separate Behavior block for billing and latency. Some sentences duplicate structured fields — the $0.50 cap, the 50-item default, and the 300 s max are all in the schema — which makes the block denser than necessary, though nearly every sentence still carries routing or billing value.

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 12-parameter, zero-required, actor-wrapping tool with no output schema and real per-item cost, the description covers purpose, alternatives, cost model, timing, failure recovery ('raise run_timeout_secs ... or shrink the input after a timeout error'), and even enumerates returned fields. An agent has everything needed to call it safely and interpret the response.

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 and individual parameter meaning is already documented. The description earns extra credit for cross-parameter interactions the schema does not state: empty keywords plus filters yields a large set, includeDetails/includeDodQa cost time but not money ('same price'), and run_max_items fills maxResults when unset. It stops short of a 5 because much of the parameter prose restates schema text rather than adding new semantics.

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 SBIR and STTR solicitation topics across agencies') and enumerates the return payload (close dates, days left, topic numbers, official links, DoD Q&A status, TPOC). It explicitly distinguishes itself from the two nearest siblings, grants_finder and federal_contract_finder, so an agent can route correctly without comparing 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 gives explicit when-to-use ('a small business or research partner needs open SBIR/STTR topics, deadlines or a TPOC to contact') and explicit when-not-to-use with the named alternative for each exclusion ('Do not use for general grants (use grants_finder) or for past contract winners (use federal_contract_finder)'). It also supplies tactical guidance per parameter, e.g. keep maxResults low with empty keywords, and use status=closed for historical funding patterns.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, and the description stays consistent while adding substantial context the annotations cannot carry: SEC fair-access contact requirement, $0.002 per company-year billing, that run_max_items does not limit the Actor's billing while run_max_charge_usd does, default $0.50 cap, 5-15 s typical latency with run_timeout_secs up to 300, and that unknown tickers come back free with a status. Non-idempotency is implicitly covered by per-call billing and the explicit warning about repeated cost exposure.

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?

Front-loaded with purpose, then routing, then parameter cost guidance, then runtime behavior — a sensible order. It is long and dense, and the exhaustive return-field list in the middle sentence competes with the usage guidance for attention, but since no output schema exists the field inventory earns its place.

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?

Covers everything an agent needs for a 6-parameter, billed, long-running remote Actor call: cost model and caps, timeout guidance and remediation, required SEC contact email, per-item return fields in the absence of an output schema, and where the workbook artifact lands. Nothing material is left to inference.

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 baseline is 3, but the description adds real interpretation: it explains the years/company-year cost coupling and warns that run_max_items does not set years, so cost must be capped with years plus run_max_charge_usd — a cross-parameter interaction the schema only hints at. It slightly restates schema content (contactEmail's SEC purpose), which keeps this 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 — 'Return standardized annual financials for US-listed companies from SEC EDGAR XBRL 10-K data' — and enumerates the content (income statement, balance sheet, cash-flow lines plus EBITDA, FCF, net debt, margins, growth) at one row per company-year. It explicitly contrasts itself with pdf_table_extractor (best-effort PDF tables vs. exact structured filings) and federal_contract_finder (fundamentals vs. government spend), so an agent can separate it from siblings without opening a 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 an affirmative trigger ('Use when you need comps, model inputs or multi-year history for tickers or CIKs') and explicit exclusions ('Do not use for private companies, foreign filers without 10-Ks, quarterly data or share prices'). It also names the two alternatives it supersedes, which is the full when/when-not/alternative triad.

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