list_measures

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

Annotations already carry readOnlyHint=true, idempotentHint=true and openWorldHint=false, which the description does not contradict. Beyond that, the description adds real behavioral value: it discloses that an invalid category_code is an error, that an empty result can only mean an invalid category (since every Annex II category has measures), and that level accepts 'basico' as a compatibility alias.

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 definition front-loads the one-line purpose before the parameter breakdown, and each parameter note earns its place with concrete values and examples. It is somewhat long for a listing tool, but the organization is logical and there is no filler.

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 7 parameters, 0% schema coverage, and an output schema that covers return values, the description explains the three filtering dimensions in depth but omits the pagination and output-format controls. An agent calling with limit/cursor would have no documentation of how pagination behaves, which is a meaningful gap for a list tool with plausible large result sets.

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?

With 0% schema description coverage, the description must compensate, and it does well for three of seven parameters: category_code gets concrete examples ('mp.if' or 'mp') plus error semantics, dimension gets all five allowed values, and level gets its values plus the 'basico' alias. But limit, cursor, compact and include_norm_text are left unexplained; their names are partially self-evident but the pagination semantics (limit units, cursor mechanics) are not documented.

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 opening sentence 'Lista medidas de seguridad con filtros opcionales' states a specific verb (listar), a concrete resource (seguridad/security measures), and the filtering behavior, which lets an agent tell it apart from list_categories and get_measure. It doesn't explicitly contrast with search_measures, so it falls just short of full 5 differentiation, but the core purpose is unambiguous.

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 gives no guidance on when to use this tool versus its siblings search_measures or get_measure, and states no exclusions. The filter parameter notes imply a use case (filtered listing), but nothing tells an agent why to choose list_measures over search_measures when a broad or fuzzy search is needed.

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