opennih

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds real behavior: no pagination, fiscal-year bounds 1985-2100 with start<=end, and that ic is free-text with no length cap. It doesn't state response shape, but an output schema exists so that burden is lower.

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 the trigger phrase and examples, then scope, then bounds. Slightly dense with quoted user examples and a trailing bounds list, but every sentence carries information an agent needs.

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 trigger, scope, alternative routing, temporal bounds, and pagination behavior; the output schema handles return values. The main gap is not specifying valid ic values, which matters given 0% schema coverage and free-text input.

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 0%, but the description compensates partially: it explains fiscal_year_start/end constraints and notes ic is a free-text Institute filter with no length cap. It does not, however, explain what values ic accepts (e.g., IC abbreviation vs. full name) or the null-default semantics, leaving real ambiguity for a 0%-coverage schema.

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?

Specific verb+resource: returns counts and totals per NIH mechanism class from ranking_core.classify. The title and description together make the scope (whole-NIH or one Institute) unmistakable, and it names the sibling surface (institution-profile) that handles the other scope.

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?

Opens with explicit 'Use this tool when...' plus three concrete user phrasings, then names an alternative surface and the condition that selects it ('per-institution portfolios are served by the institution-profile surface instead'). Both when-to-use and when-not are present.

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 readOnly/idempotent, and the description adds real behavioral context beyond them: PROJECT-level resolution returning the LATEST fiscal year with metadata.matching_rows, plus error behavior for unmatched ids and the snapshot-cutoff caveat for 'missing' grants. That is exactly the kind of context annotations cannot carry.

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 and return shape, then constraints and edge cases in priority order. It is dense but nearly every sentence carries unique information; the final snapshot-cutoff sentence is slightly over-explained.

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?

Even though an output schema exists, the description still previews the response fields and URL purpose, and covers the level-of-aggregation subtlety and failure mode. Nothing an agent needs to call it correctly is 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 description coverage is 0% and the sole parameter is undocumented in the schema, so the description carries the full burden — and does: required, full NIH project number format, regex ^[A-Z0-9-]{1,24}$, a concrete example (1R01CA123456-01A1), and the explicit exclusion of core/partial numbers.

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 ('retrieve the full record for one NIH grant by its id') and discloses the return shape ({id, title, text, url, metadata}). It clearly separates itself from the list/search siblings by being a single-record citation wrapper.

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?

Implies the condition of use (you already hold a full NIH project number) and warns that core project numbers and partial numbers do not match. It does not explicitly name which sibling to use instead when you don't have an id, so it stops short of full when/when-not routing.

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 the safe read-only, idempotent, non-destructive profile, and the description goes well beyond them: percent-vs-fraction semantics, removal of the old `cagr` key, NULL awards excluded rather than zero-padded, meta echo for looped calls, and no pagination.

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-loads the when-to-use condition and then packs scope, semantics, and bounds into tight clauses with no filler. It is long and dense, but each sentence carries distinct operational information.

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?

An output schema exists, so return structure need not be documented, yet the description still clarifies the units of yoy_growth_pct and cagr_pct. Combined with entity scoping, date bounds, NULL handling, and pagination status, an agent has everything needed to call it correctly.

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 0%, so the description must carry the burden and largely does: entity_id is defined as the canonical institution identifier matched exactly with no length cap, and fiscal years are bounded 1985-2100 with fiscal_year_start <= fiscal_year_end. It adds real meaning beyond the bare integer/string schema.

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+resource: growth RATE of NIH funding for an institution or all NIH. Explicitly distinguishes rate-of-change from level-of-funding, which is exactly the axis separating it from the funding_trend sibling.

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 triggering questions ('is this university's NIH funding growing', 'what's the CAGR since 2015', 'who grew fastest') and the rate-vs-level condition. It implies the alternative (a level/trend tool) but never names funding_trend or another sibling explicitly.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's value is in the extra behavior it discloses: FY bounds 1985-2100, fiscal_year_start <= fiscal_year_end, no pagination, partial-current-year row flags, and the 1.5-1.7x magnitude gap versus ranking totals. What it omits is edge behavior for out-of-range or empty results, keeping it short of a 5.

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 and triggers, then scope caveats, then constraints — a sensible order with no filler sentences. It is dense and runs long, particularly the SQL-injection aside, but each clause carries usable information.

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?

An output schema exists, so return-shape explanation is unnecessary; the description instead supplies everything an agent needs to call this correctly — valid filter dimensions, year bounds, non-pagination, and the comparability caveat. Nothing material is 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 description coverage is 0%, so the description must carry parameter meaning, and it does: ic, activity_code and institution are named as free-text filters, and the numeric bounds plus start<=end constraint on the fiscal year params are spelled out. It doesn't state the default behavior when all filters are omitted beyond the implicit 'whole NIH' scope.

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 (yearly NIH funding totals and grant counts) plus the exact slice granularity (whole NIH, one IC, one activity code, one institution). An agent can distinguish this from funding_growth or topic_trend without opening either 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?

Provides concrete trigger questions ('how much NIH funding was awarded in FY2020', 'plot R01 dollars by year') that map directly onto the tool's slice parameters. It also warns that total_funding is not comparable to research-only ranking totals, which steers the agent away from misuse against ranking siblings.

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 cover readOnly, idempotent, non-destructive and closed-world, yet the description adds substantial non-obvious behavior: fiscal-year scoping applies to every aggregate section, provenance.fiscal_year_window echoes the applied window, meta.found is an explicit boolean with profile=null on miss, and meta.found/profile.organization are deliberately window-independent. It also discloses the null fiscal_year semantics (never 0, belongs to no window), which is genuine behavioral disclosure not present in 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?

Usage guidance is front-loaded before the data-shape details, and nearly every sentence carries unique semantics. It is dense and long, with some near-overlap between the window-independence sentence and the meta.found boolean sentence, so it is efficient but not maximally tight.

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 single-entity lookup with an output schema, the description supplies everything an agent needs beyond the schema: identifier provenance, scoping rules, miss handling, and null-year edge cases. No material gap remains even though return values are formally covered by the output schema.

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 0%, so the description carries the full burden and does so: entity_id is defined as the canonical institution identifier with its source and a 2-256 character bound, and fiscal_year_start/end are explained as scoping EVERY aggregate section (mechanism-mix, funding-trend, top-PIs) with omit-both meaning all years and a 1985-2100 bound. This far exceeds the schema's bare titles and defaults.

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 names a specific verb and resource ('Read-only institution profile: funding history, mechanism mix, top PIs') plus a concrete triggering intent ('the user asks about one named institution'). It is instantly separable from get_pi_profile, rank_institutions, and search_grants, since it is explicitly scoped to one institution's NIH profile.

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 trigger context with quoted example queries and tells the agent where entity_id comes from ('from the institution ranking') while warning that grant-search results do NOT carry one — effectively routing between siblings. It stops short of naming the reciprocal tools (rank_institutions, search_grants, get_pi_profile) as in-when/when-not alternatives.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: count semantics for grant_count vs active_grants, collaborator coverage gaps, PI-role matching limits, and subproject NULL meaning. Slightly reduced only because it leans heavily on issue-numbered jargon that an agent must decode.

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 the usage trigger, then organized into clearly labeled sections (COUNT SEMANTICS, COLLABORATOR COVERAGE, PI ROLE, SUBPROJECT ROWS, Bounds), so it stays navigable despite its length. Some density comes from issue references (#762, #761, #342) that add noise rather than actionable guidance.

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 an output schema exists and safety is covered by annotations, the description supplies the semantic caveats needed to interpret results: aggregate scoping, collaborator coverage flags, PI-role flags, and subproject NULL handling. Only minor gaps remain, such as explaining what limit/offset paginate over.

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 compensates fully: profile_id is explained as the NIH RePORTER identifier carried in pi_profile_id, not guessable, with a digit regex; fiscal year parameters are shown to scope every aggregate section; and limit/offset bounds and defaults are stated.

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 concrete verb+resource ('Read-only PI profile: grants, collaborators, publications, funding totals') and immediately conveys the object is one researcher, with distinguishing detail that the headline name/institution follow the latest grant. An agent can distinguish it from institution-level siblings like get_institution_profile.

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?

Opens with an explicit trigger ('when the user asks about one researcher') plus example utterances, explains where profile_id comes from, and clarifies that an empty fiscal-year window is not an error. It does not explicitly name a competing sibling tool to route away from, so it falls short of a full when/when-not/alternatives statement.

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 cover readOnly/idempotent/non-destructive, and the description adds substantive behavior beyond them: the match_strategy surface ('rcdc' vs 'text'), the measured 50% RCDC-density threshold that forces the text fallback, provenance.rcdc_window_coverage, and the de-duplication rule that each grant is counted once. It also flags that results are not paginated, which the annotations do not convey.

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 trigger condition and examples are front-loaded, followed by the response-surface explanation and then constraints, which is a sensible order. The prose is dense and every sentence carries information, though the parenthetical density explanation could be tightened.

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 two-surface cross-tab tool with an output schema already defining return values, the description supplies everything else an agent needs: required params, character and fiscal-year bounds, the surface-selection rule, provenance semantics, de-duplication, and the no-pagination fact. 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 0%, so the description carries the load and does: both ic and query are required at 2-64 characters, fiscal years span 1985-2100 with start <= end, and ic='ALL' is a valid sentinel. match_strategy's 'auto' default and its allowed values are only partly explained (the 'rcdc'/'text' surfaces are described but 'auto' selection logic is not).

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 states a specific verb and resource ('what ONE NIH Institute funds in a topic') with concrete example queries, so an agent immediately knows this is an IC-by-topic cross-tab rather than a trend or search tool. It never names a sibling (topic_trend, funding_trend) to contrast against, which is the only thing keeping it from a 5.

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 trigger conditions with quoted user phrasings ('what is NCI spending on immunotherapy', 'compare NIAID and NCI on vaccines') and tells the agent to call it once per Institute for comparisons. It also implicitly routes away from itself when a trend is needed, but no alternative tool is named for that case, so there is no true when-not guidance.

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?

Beyond the read-only/idempotent annotations, it discloses the analysis scope (competitive RPG-research, NULL awards excluded, never padded to $0), fiscal-year bounds (1985-2100, start <= end), non-paginated behavior, and how ambiguous `ic` values are handled with a `meta.ic_scope.kind` report. This is exactly the operational context annotations cannot carry.

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 the use case, then output, scope, bounds, and the `ic` caveat in a logical order; every sentence carries distinct information. It is dense and slightly long, but no sentence is filler.

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?

An output schema exists, yet the description still names the key metrics, and it covers the edge cases an agent would otherwise guess at (null handling, year bounds, fragment matching, no pagination). Nothing needed to invoke or interpret it correctly is 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?

With 0% schema description coverage, the description carries the full burden and does so: `ic` is explained as either an IC abbreviation (NCI, NIGMS) or a matched name fragment spanning multiple institutes with a reported `fragment` kind, and the two fiscal-year parameters get valid range and ordering constraints. Omission of `ic` meaning all-NIH is also stated.

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 resource (NIH funding concentration across institutions) and the exact metrics returned (gini, hhi, top5_share, top-5 institutions), which cleanly separates it from siblings like rank_institutions and funding_trend. An agent can select it 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?

Opens with an explicit trigger ('Use this tool when the user asks how concentrated or unequal NIH funding is...') and supplies sample user phrasings, giving clear context for selection. It does not explicitly rule out or name alternative siblings (e.g. rank_institutions) for adjacent questions, so it stops short of full when-not guidance.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description goes well beyond them: counts are grouped by comparability_group and never summed across classes, entity_id is matched exactly with padded/unpadded DUNS both resolving, there is no length cap, and results are not paginated. These are behavior traits no structured field communicates.

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-loads the usage trigger, then scopes, then parameter and bound constraints, then pagination — a logical order with no filler. Every clause (non-comparability, grouping rule, DUNS spellings, year bounds) carries operational meaning.

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?

An output schema exists, so return-value description is correctly omitted. Scope definition, the non-comparability warning, exact-match and DUNS behavior, and fiscal-year bounds cover everything an agent needs to invoke this 3-param, all-optional tool correctly.

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 0%, so the description carries the full burden and does much of it: entity_id's origin ('canonical institution identifier from the institution ranking') and matching semantics are defined, and the fiscal-year bounds (1985-2100, start <= end) are given. It does not explain what a null/omitted entity_id or null fiscal years resolve to as defaults, which is the remaining gap.

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 resource and scope: 'what mix of award types ONE institution wins' with concrete example questions about R01s, centers, and training money. The two-scope behavior (entity-scoped portfolio vs system-wide RPG breakdown) is spelled out. It falls short of 5 only because it never mentions the closely related sibling activity_code_distribution, so the agent must infer the boundary from names alone.

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?

Opens with an explicit trigger ('Use this tool when the user asks...') and supplies three example user phrasings that map to this tool. It also warns that the two scopes are NOT comparable, which prevents a plausible misuse. It does not name a competing tool or state when another sibling should be chosen instead, keeping it below 5.

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 the read-only/idempotent safety profile, and the description adds substantial context on top: the RPG-research-only scope, exclusions (intramural/contracts/centers/career/training), de-duplication on core_project_num, and the rule that NULL total_funding is omitted rather than shown as $0. The comparability caveat prevents a serious downstream misreading.

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 the when-to-use trigger, followed by output, methodology, the comparability warning, and bounds. Dense but every sentence adds decision-relevant information with no filler.

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 an output schema present, the description needn't explain return shape, yet it still notes the ranked rows yield entity_id. Combined with full bounds and scope caveats, an agent has everything needed to invoke this correctly.

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 0%, so the description carries the full burden and does so: it documents limit (1-50, default 20), offset (0-100000), fiscal years (1985-2100), ic format (2-64 chars, abbreviation or code) with examples, and enumerates all five sort_by values. This is near-complete parameter documentation despite the empty schema.

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 states a specific verb and resource ('Ranks institutions by competitive RPG-research NIH funding') and immediately scopes it with the R01 baseline and exclusions. It is clearly distinguishable from siblings like get_institution_profile or institution_concentration.

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 triggering conditions with concrete user phrasings ('top NIH-funded universities', 'rank research hospitals by R01 funding'). It also warns the totals are not comparable to all-mechanism figures 'served elsewhere', but it never names the specific sibling tool an agent should switch to, so it stops short of full when-not/alternative routing.

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 cover the read-only/idempotent safety profile, and the description adds substantial non-obvious behavior: project-level dedup, canonical-row resolution independent of the query, why titles may not contain query terms, cross-page duplicates, and offset stepping. This is exactly the kind of context annotations cannot express.

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 the use case, then return shape, then semantics, then bounds, so an agent can stop reading early. It is dense but slightly redundant: 'ids are unique within a response' and the canonical-row explanation are each restated, adding length without new information.

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 3-parameter tool with a deceptively complex result model and pagination, nothing an agent needs is missing; the only gap is return-format detail, which the output schema already supplies.

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 0%, so the description carries the full burden and does: query is required, 2-64 chars, matched over titles, blank yields nothing; limit 1-50 default 20; offset 0-10000 with exact row-skipping semantics. That is more than the schema's bare types and defaults provide.

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 ('citation-shaped NIH grant hits') and defines the record shape (id = project_num, url = OpenNIH page). It explicitly distinguishes itself as the 'citation-record wrapper' with no filters, which separates it from the filterable search_grants sibling.

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 a clear triggering condition ('when a research or connector client needs citation-shaped NIH grant hits for a natural-language query') and exclusions ('takes no filters... returns no funding totals or provenance'). It never names search_grants as the alternative for filtered/aggregate needs, so routing is implied rather than explicit.

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?

The description adds substantial behavior beyond the annotations: caching for about one hour, offset rate limiting above 10,000, null award_amount semantics, PI name matching order, and row-level counting rules. It also explains that multi-component awards emit multiple application-year rows and identifies appl_id as the authoritative row identity.

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 front-loads the intended use cases and key examples before moving into operational details. Most sentences carry useful constraints or caveats, though the counting and deduplication explanation is dense enough to feel somewhat overloaded.

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 complex 11-parameter search tool with very low schema description coverage, the description covers most critical invocation behavior, including bounds, caching, rate limits, and row-counting semantics. The remaining gap is partial explanation of some parameter distinctions and matching rules, though the output schema exists and reduces the need to explain return fields.

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 only 9%, so the description must compensate, and it does for many parameters by giving length bounds, regex constraints, fiscal-year range, limit/offset ranges, and PI name matching behavior. It leaves some ambiguity around ic, query vs text_search, and institution matching semantics, so it is strong but not complete.

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 states a specific verb and resource: search NIH grants by topic, PI, institution, IC, activity code, fiscal year, or project number. It explicitly positions this as the primary entry point and differentiates it from analytics-style siblings by describing row-level grant search behavior.

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 concrete user-intent examples such as finding grants on CRISPR, Stanford R01s in 2022, or looking up a specific project number. It clearly states when to use the tool, but does not explicitly compare against siblings like fetch, search, or get_pi_profile for adjacent needs.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the corpus_lag_note snapshot-cutoff semantics that explain absence-vs-nonexistence, and the constraint that no caller paths or external URLs are accepted. Return details are covered by the output schema, so nothing further is required.

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?

Three sentences, front-loaded with the usage trigger before the purpose statement, and each sentence carries distinct information. Slightly dense in the opening clause about corpus_lag_note, but no filler.

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?

Complete for a no-param status tool: purpose, trigger conditions, the interpretation caveat for missing grants, and input constraints are all covered. With annotations and an output schema present, no further behavioral disclosure is needed.

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?

Zero parameters, so the baseline is 4. The description usefully confirms this by stating it takes no parameters and accepts no caller paths or external URLs, matching additionalProperties=false in the schema.

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 states a specific verb and resource: 'Read-only status for the deployed NIH project corpus and official sidecars.' It also enumerates what status means (whether corpus is loaded, which sidecars exist, staleness), clearly distinguishing it from query siblings like search_grants or fetch.

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 trigger conditions ('when the user asks whether the OpenNIH corpus is loaded, which official sidecars are available, or how stale the data might be') plus a precondition for use before reporting 'no such grant'. The negative case — grant absent because it postdates the snapshot cutoff — is spelled out rather than left to inference.

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 declare readOnly/idempotent/openWorld=false, but the description adds real behavioral context beyond them: the AND-in-any-order multi-word semantics, 'not paginated', the returned shape (yearly counts plus recorded award totals), and hard bounds. Contradicts nothing.

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 the trigger and examples, then constraints. Slightly dense in the middle clause but every sentence carries information an agent needs to call the tool correctly.

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?

Covered: trigger, match semantics, return shape, bounds, pagination. An output schema exists so return values needn't be detailed. Minor omission is the meaning of null fiscal year bounds, but the definition is otherwise sufficient for correct invocation.

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 0%, so the description must carry parameter meaning, and it does: query is REQUIRED and 2-64 chars, fiscal years 1985-2100, and start<=end. It omits explaining what happens when fiscal_year_start/end are null (default), a minor gap.

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+resource (topic funding trend over time) with concrete example queries, and distinguishes from siblings like funding_trend and funding_growth through the title-keyword framing and the 'how has a topic trended' use case.

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 explicit trigger phrasing ('Use this tool when the user asks how a research topic has trended over time') plus three example queries, but does not name the sibling alternatives (funding_trend, funding_growth) or clarify when-not to use it.

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