naep_compare_years

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotation: it explicitly states that the tool performs significance testing and reports whether changes are statistically significant, which is a non-obvious output behavior. This adds value without contradicting 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 three concise sentences, each earning its place: the first states the core purpose, the second clarifies the significance-testing behavior, and the third offers a concrete use case. It is front-loaded and free of redundant or filler content.

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 moderate complexity, no output schema, and the richness of sibling tools, the description adequately covers the tool's purpose, key feature (significance testing), and a practical use case. It does not enumerate return fields, but the absence of an output schema makes some output ambiguity acceptable. It is sufficiently complete for an AI agent to select this 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?

The input schema provides 100% coverage with descriptions for all five parameters, including format examples and valid values. The description does not add parameter-level detail beyond the schema, and the mention of 'years' in the description merely restates what the schema already documents. Baseline 3 applies because the schema carries the load.

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 ('Compare') and resource ('NAEP scores across assessment years'), and further clarifies the unique value proposition: significance testing of score changes. This clearly distinguishes the tool from siblings like naep_compare_states and naep_compare_groups, which focus on other comparison dimensions.

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 provides clear contextual guidance by noting it's 'Great for tracking the COVID learning loss and recovery,' implying when year-over-year comparisons are relevant. However, it does not explicitly state when to avoid this tool in favor of state or group comparison tools, so it lacks explicit exclusions.

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