Citations_get_citation_statistics

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

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: criteria is validated against an enriched field whitelist, OA-only clauses cause a 400, there is no lane parameter, and the OA index has no statistics path. It also states the returned fields for the enriched lane. This goes well beyond the annotation and gives the agent an accurate model of the tool's behavior and constraints.

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 longer than average, but every section earns its place: purpose, lane limitation, workaround, and return summary. The bold ENRICHED LANE ONLY warning is front-loaded, and the example is compact and directly useful. Given the complexity of the lane distinction, the length is appropriate and well structured.

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 one optional parameter, an output schema, and readOnlyHint already present, the description covers the essential contextual gaps: what the tool aggregates, what lane it targets, what happens on invalid criteria, how to handle the OA lane, and what the return shape is. The agent has enough information to select and invoke this tool correctly in almost any scenario.

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?

The schema provides only a 'criteria' string with a default of '' and zero description coverage, so the description carries the full burden. It does explain that criteria is validated against the enriched field whitelist and gives an example query ('techCenter:2100 AND legalSectionCode:103'), but it does not fully define the general query syntax or what an empty default means. Still, it adds substantial meaning beyond the bare 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 opens with a clear verb and resource: 'Get database statistics and aggregations for strategic planning.' It then enumerates what counts as statistics (counts, totals, aggregate, distribution, breakdown by art unit/tech center, trends over time, citation volume), which sharply distinguishes it from sibling search tools. This makes it immediately clear this is an aggregation tool, not a search or details tool.

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?

The description explicitly states 'ENRICHED LANE ONLY' and explains when to use an alternative: 'To aggregate the OA lane, count it yourself with the OA search tools.' It even provides a concrete example call and explains the limitation is 'a documented limit, not a bug to work around by rephrasing the clause.' This is model usage guidance with both when-to-use and when-not-to-use.

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