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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the preview sends nothing, that confirming sends a REAL aviso to the city council, and that the photo is only uploaded during that confirmed send — an irreversible side effect clearly flagged. It also documents the return payload (JPEG ≤1024px sans EXIF thumbnail, or the raw small PNG, and the need_description phase).

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?

Dense but front-loaded — the two-phase nature and the preview-vs-confirm split arrive first, with the thumbnail/phase:need_description detail trailing. Some sentences run long, but each carries actionable constraints (mandatory photo, confirmation gating, no inference submission) rather than 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?

For a 15-parameter mutation tool with no annotations and no output schema, the description supplies the workflow, side-effect profile, error branch, and return-value semantics an agent needs. Little is missing to call 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 100%, so baseline is 3, but the description adds real meaning by assigning parameters to phases: which fields belong to the preview call and which (preview_token, confirm, human_confirmed) are confirmation-only. This sequencing context is not derivable from the flat schema.

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?

Opens with a specific verb+resource in the domain's own vocabulary ('Única herramienta para avisos, en dos fases'), immediately distinguishing it from the read-only siblings (list_my_avisos, list_categories). An agent knows this is the write path for filing a report.

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?

Explicit two-phase flow: preview with aviso fields + mandatory photo and no token, then confirm only with preview_token/confirm/human_confirmed. It states when-not (never submit by inference) and the recovery path (if the user requests changes, create a new preview). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden, but 'Lista' clearly signals a read-only enumeration and it discloses the shape of the returned data (ids and names). It says nothing about authentication, pagination, or whether the list is static or filtered by the caller's tenant.

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?

A single, front-loaded sentence with no filler. It could be slightly tighter but every clause contributes (scope, platform, returned fields).

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?

For a simple, parameterless read-only list tool with no output schema, the description is adequate: it states the scope and what each entry contains. The missing pieces (auth, whether results are exhaustive) are minor for this complexity level.

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 description coverage is 100%, so the single 'search' parameter is already documented in the schema with examples. The description adds no filtering semantics beyond what the schema provides, which is the expected baseline.

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 gives a specific verb+resource ('Lista todos los municipios') and even states the returned content (identificadores y nombres). It is clearly distinguishable from set_ayuntamiento, though it doesn't name siblings explicitly.

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?

There is no statement of when to use this versus alternatives. The natural use case – looking up a municipality identifier before calling set_ayuntamiento – is left entirely to inference.

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

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

No annotations are provided, so the description carries the full burden. It is clearly a read-only catalog fetch and it usefully discloses the shape of the returned taxonomy (families, elements/subcategories, types), which substitutes for a missing output schema. However, it says nothing about whether results are cached, paginated, or how large the catalog is.

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?

A single, front-loaded sentence with no filler. Slightly dense parenthetical enumeration, but every clause earns its place by describing the returned taxonomy.

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?

For a simple catalog-listing tool with one optional parameter and no output schema, the description is largely sufficient: it names the resource, its scope (active ayuntamiento), and the structure of the returned data. Only the when-to-use framing and any behavioral caveats are missing.

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% with a single optional 'search' parameter fully documented in the schema. The description adds no parameter detail beyond the schema, so the baseline of 3 applies.

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 verb+resource: retrieves the catalog of incident typologies (families, elements/subcategories, types) for the active ayuntamiento. This is clearly distinguishable from the sibling tools (whoami, list_ayuntamientos, set_ayuntamiento, resolve_location, etc.), which handle identity, municipality selection, and location rather than taxonomy. It doesn't explicitly name a sibling, but the resource is specific enough.

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?

No explicit when/when-not guidance or named alternatives. The phrase 'para el ayuntamiento activo' implicitly signals a dependency on set_ayuntamiento having run first, which is useful implied context, but it is left for the agent to infer. Minimum-viable implied usage.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It indicates the tool reads previously registered notices and returns their processing status, but does not state read-only safety, authentication requirements, pagination, or return format.

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 a single sentence, front-loading the action. However, it redundantly uses 'Consulta' and 'para consultar', slightly reducing efficiency.

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?

For a parameterless list tool with no output schema and no annotations, the description gives the basic purpose and the type of information returned (processing status). However, it omits usage context, behavioral traits, and return format details, leaving some gaps for an agent to infer.

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 tool takes zero parameters, so the schema provides no parameter semantics. Per the rubric, zero parameters yields a baseline score of 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 states a specific verb ('Consulta') and resource ('avisos'), and adds the scoping detail that these are the user's previously registered notices, queried to check processing status. It does not explicitly differentiate from sibling list tools (e.g., list_ayuntamientos, list_categories), but the resource is distinct enough for an agent to distinguish.

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?

No guidance is given on when to use this tool versus alternatives, nor are any exclusions or prerequisites stated. The purpose implies usage, but the description does not explicitly say when an agent should select this over other listing tools.

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

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

With no annotations, the description carries the full burden. It usefully discloses the state dependency on the 'municipio activo' (implying set_ayuntamiento must run first) and that resolution is against the official GECOR callejero, which implies a read-only lookup. It does not say what is returned, how ambiguous street matches are handled, or what happens when coordinates fall outside the municipality.

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?

A single efficient sentence with the action front-loaded and the two input modes trailing. No filler, though the purpose and the mode list are packed into one clause with no visual separation.

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?

No output schema exists, so the description arguably should say what a resolved location looks like (canonical street, ID, coordinates). It also omits what happens with no required parameters supplied and whether the active municipality is a hard prerequisite. Adequate but with clear gaps for a 3-param resolver with no annotations.

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 description coverage is 100%, so the schema already documents lat, lng and street_name with examples. The description's only added semantics is that coordinates and street search are alternative modes rather than a combined query, which is genuine but modest value on top of the schema.

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 verb pair (valida y resuelve) and resource (una ubicación), plus the scope (municipio activo) and the two accepted input modes. An agent can tell it apart from the siblings (whoami, list_avisos, create_aviso_from_photo) without opening the schema, though it doesn't explicitly name any sibling.

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 implies when the tool applies by naming two entry paths (GPS coordinates or street lookup in the callejero), which is useful routing information. However, it gives no explicit when-not guidance, no prerequisites (e.g. that an active municipality must first be set), and no error/ambiguity handling.

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

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

With no annotations the description carries the full burden, and it does disclose the effect scope (the active municipality applies to queries and incidents), which is real behavioral context. However, it is silent on persistence across sessions, permission requirements, and what happens with an invalid ID.

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?

A single front-loaded sentence with zero waste; the action and its effect are stated immediately.

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?

For a simple one-parameter state-setting tool with no output schema, the description covers the essential purpose. It omits the practical prerequisite of sourcing a valid ayuntamientoID (e.g., via list_ayuntamientos) and any persistence/error behavior, leaving modest gaps.

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 description coverage is 100%, so the single parameter ayuntamientoID is already documented in the schema with an example value. The description adds nothing beyond the schema, so the baseline 3 applies.

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 verb and resource: 'Cambia el ayuntamiento activo' (changes the active municipality). An agent can tell it is a setter of session context, distinct from the sibling list_ayuntamientos which enumerates them. It does not explicitly name a sibling to differentiate against, keeping it short of a 5.

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?

'para las consultas e incidencias' implies the change scopes subsequent queries and incident calls, which is implicit usage guidance. There is no explicit when-to-use, no note that the ID should first be obtained from list_ayuntamientos, and no when-not-to-use.

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

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

No annotations are provided, so the description carries the burden. It discloses the two pieces of state returned (active municipality, token configuration), which implies a read-only diagnostic, but never states that it is non-mutating, what permissions it needs, or whether it makes a network call. Minimum viable for a trivial zero-param tool.

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?

A single sentence that front-loads the primary output and adds the token-check detail second. No filler, no redundancy.

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 no output schema and no annotations, the description must explain what comes back, and it does name both return values. It could specify the response format (e.g. booleans, string names), but for a trivial state-check tool it is essentially complete.

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 schema defines zero parameters, so there is nothing for the description to clarify. Baseline of 4 applies since no parameter ambiguity exists.

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 gives a concrete verb and two specific outputs: it shows the active municipality and whether GECOR_TOKEN is configured. This is clearer than the bare name 'whoami' and distinguishes it from setters like set_ayuntamiento. It does not explicitly name the sibling it differs from, so it stops short of a 5.

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?

There is no statement of when to call this tool, when not to, or which alternative to prefer. Usage is only implied by the fact that it reports current state. An agent gets no routing guidance versus list_ayuntamientos or set_ayuntamiento.

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