Grant/denial statistics over decided hearing-level DOHA cases, grouped by year or by guideline, always with sample sizes. Same population rules as the site's Insights page.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | Grouping (default year) | |
| year_to | No | ||
| guideline | No | Optional single guideline letter A-M to scope to | |
| year_from | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral context about the population scope ('decided hearing-level DOHA cases') and output characteristic ('always with sample sizes'), which goes beyond the structured fields without contradicting them.
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?
Two short sentences deliver the essential purpose, scope, grouping, and sample-size behavior. There is no filler or repetition, and the front-loaded verb 'statistics' immediately conveys the tool's function.
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?
The description covers the core scope and grouping, offering a reference to the Insights page for population rules, and hints at output via sample sizes. However, it does not mention the year range parameters, output structure, or behavior for missing optional parameters, and there is no output schema to fill these gaps.
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 50%; the description clarifies the 'by' parameter by mentioning grouping by year or guideline, but the year_from and year_to parameters are completely undocumented in both schema and description. This leaves the date range filtering ambiguous, and the description does not compensate for the 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?
The description clearly states the tool provides 'grant/denial statistics' over a specific case population ('decided hearing-level DOHA cases'), with grouping options ('by year or by guideline') and a guaranteed trait ('always with sample sizes'). This distinguishes it from sibling tools focused on individual cases or other outcome types.
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?
Usage is implied for aggregate statistics needs, and the reference to the site's Insights page provides a population-rule context. However, there is no explicit exclusion such as 'for individual case details, use get_case' or other alternative comparisons, so guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct function: searching, retrieving a specific case, finding similar cases, and four different statistical analyses (overall, candor-related, conduct recency, and timeline). No two tools overlap in purpose.
All tool names follow a clear verb_noun pattern: get_ for retrieval, search_ for searching, similar_ for similarity. The verbs vary appropriately with the action, and snake_case is used consistently.
Seven tools is well within the ideal range for a search-and-analytics server. Each tool covers a necessary capability without redundancy or bloat.
The tool set covers the full workflow: comprehensive searching (search_cases), detailed case retrieval (get_case), similarity exploration (similar_cases), and four distinct statistical views (candor, conduct recency, overall statistics, timelines). No significant gaps are apparent for the stated purpose.