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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail beyond annotations: undated items are counted in undated_count and never dropped silently; month-granularity keeps bare-year keys for items dated only to a year; hijri buckets require full YYYY-MM-DD, with imprecise dates reported in imprecise_date_count. Also explains the lunar_month collapsing behavior and the ~11-day drift reason. No contradiction with 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?

The description is long but each sentence earns its place. It fronts the main purpose, then covers subsets, filters, grouping, date precision handling, and the hijri calendar use case. The structure flows logically from general function to specific exceptions, and no sentence is redundant with the schema or annotations.

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 the tool's complexity (10 optional parameters, two calendars, group_by, and date precision edge cases), the description is remarkably complete. It covers all key behavioral aspects: counting aggregation, applicable subsets, filter compatibility, grouping behavior, and handling of undated/imprecise dates. An output schema exists, so return values are documented elsewhere. No major gaps remain.

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 baseline is 3. The description adds meaning beyond the schema: it clarifies that keyword is exactly ONE substring, explains the interaction between calendar=hijri and granularity=lunar_month (collapsing years into twelve lunar months), and specifies that group_by returns one distribution per group. It also names the shared filter set (country, newspaper/series, subject, date range) as 'the same filters as the corresponding search_* tool.' This enriches the parameter context enough to warrant a 4.

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+resource ('Counts of matching items per year (or month)') and immediately differentiates from search tools by positioning itself as 'the direct way to chart coverage trends over time instead of paging through search results.' This distinguishes it from sibling distribution tools like get_field_distribution or get_topic_distribution by emphasizing the temporal dimension.

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?

Explicitly states when to use: as a direct aggregation alternative to paging through search results. It also provides a strong exclusion/alternative note for the hijri calendar, calling it 'the ONLY way to see observance-driven coverage' (Ramadan, hajj, etc.), making clear when this tool is uniquely appropriate. No explicit 'when not to use' beyond the search alternative, but the context is unambiguous.

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