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

The annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds the limits that matter when calling: at most 1000 cells are selected, an unpublished figure comes back as null, and the table title names the unit. The 1000-cell cap and null semantics are the kind of detail only the description provides.

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?

Five short sentences cover purpose, limits, and edge cases, and the main purpose comes first. The closing 'Data from Geostat' and 'The title of the table names the unit' are low-value short notes, but they are still compact.

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?

An output schema exists, so the description need not explain the response shape, and it correctly spends its detail on the selection limit, null semantics, and defaults. The main remaining gap is sibling routing: nothing in the text points to stats_get_table for dimension codes, though the schema does.

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 code, language, selection, values, and last are all documented, and the description mostly repeats the 'dimension omitted takes every value' rule already in the schema. The null-for-unpublished detail adds a little meaning about returned figures, but nothing about the values/last mutual exclusion beyond what the schema states.

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 states a concrete verb and resource ('Returns the figures of one table of Geostat') and scopes the result ('value codes, or the last values, for each dimension'). That distinguishes it clearly from stats_get_table (metadata) and stats_search_tables (discovery) without needing either schema opened.

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 tells the agent implicitly that a selection is optional, because a dimension with no selection takes every value. It never states when to use this rather than stats_get_table or stats_search_tables, and that routing only appears as a hint in the schema ('from stats_search_tables'). The agent can infer the usage, but the description does not say it.

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