research_policy

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

Annotations only declare read-only/open-world, yet the description discloses a large amount beyond them: per-expression page caps, a fifteen-request ceiling, a six-to-seven document budget, retry rules for failed institutions, arithmetic-only funding checks, deduplication, reviewFlags, partial failures, and title_inferred vs body-supported distinctions. No contradiction with readOnlyHint/destructiveHint=false is present.

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 a single ~330-word block of telegraphic, comma-chained rules with no paragraphs, bullets, or headings, mixing search-budget limits, funding arithmetic warnings, and presentation instructions. Front-loading is fine, but the density makes several sentences ('a failed institution may be retried with another candidate') hard to parse, and much of the detail belongs in structured fields or docs.

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 no output schema, the description properly explains the returns: evidenceMap stage paths, budgetEvidenceLinks, conservative project bundles with title year, compact-field presentation with original-document links, and partial failures. It covers behavior, parameters, defaults, and outputs for a complex tool, leaving only minor ambiguity about the exact response shape.

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 only 20% schema description coverage, the description carries the load: it explains that 'queries' accepts 1-3 host-generated semantic search expressions, that 'question' is passed as-is, and that startDate/endDate must both be supplied to honor user dates (default: past two years). It adds real meaning over the bare schema, though it never states the YYYYMMDD format encoded in the pattern.

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 'Start here for a short municipal policy question' gives a clear entry-point scope, and the body implies a research/orchestration tool that searches, screens candidates, and returns bundles and evidence. The verb+resource is implied rather than crisply stated, and it never contrasts itself with siblings such as search_budget_projects or build_research_brief, only with 'comparison' and 'document references' modes.

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?

Strong entry guidance ('Start here for a short municipal policy question'), query-supply rules ('host AI can supply 1-3 semantic search expressions'), default-vs-user-supplied date handling, and a routing hint ('use comparison for a short ... table; use document references for details'). It lacks explicit when-not-to-use guidance against the other seven sibling tools, so it stops short of a 5.

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