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

Goes well beyond readOnlyHint by disclosing result-set size, that the 'worldwide' entry is a cross-study range rather than a pooled meta-analysis, and that figures are not directly comparable across studies. It also clarifies the calc flag semantics and that the data is not a diagnosis. Minor gap: no mention of ordering or whether results are cited/stable.

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?

Front-loaded with what is returned, then filter semantics, then interpretive caveats; every sentence carries information. It is dense but not padded—the caveat block is long yet materially useful.

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 four optional params, no output schema, and read-only annotations, the description supplies the filter behavior, returned field set, default behavior, and interpretation limits an agent needs to call and use it 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?

Schema coverage is already 100%, so baseline is 3; the description earns higher by specifying matching semantics the schema cannot convey — age matches when the stated age range includes it and unaged entries never match, while percent filters match on figure/range overlap. Study and percent parameters are only lightly touched, keeping it from a 5.

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?

States a specific resource (published dyscalculia prevalence figures) and immediately enumerates the returned fields, so the agent knows exactly what comes back. It explicitly routes reference-key lookups to the sibling get_reference, showing it can be distinguished from neighbors without opening schemas.

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?

Explains the three filter modes and the no-filter default ('returns all 10 entries'), and names get_reference as the companion tool for keys. It lacks an explicit statement of when to prefer a sibling like list_studies over this tool, but the usage context is otherwise clear.

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