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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them: matches can be ambiguous and the tool may return several candidates, which is why the disambiguation filters matter. It doesn't say what happens on zero matches, keeping it below a 5.

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?

Two sentences: the first front-loads what the tool does and returns, the second delivers the disambiguation rule. No filler, nothing buried.

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 5-parameter, single-required-arg read tool with full schema coverage, the description covers input intent, ambiguity handling, and return content (ids, administrative hierarchy, coordinates). No output schema is needed because the description already states what comes back.

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 the baseline is 3; the description earns extra credit by explaining the rationale behind the provincia/departamento/localidad filters rather than just restating them. It adds no new detail on 'max', which the schema already documents.

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 (normalize a free-text street address) and spells out the output shape: street id, department, province and coordinates. That forward-geocoding framing inherently distinguishes it from reverse_geocode and from the search_* administrative lookups.

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?

Gives an explicit conditional: pass provincia, and optionally departamento or localidad, to disambiguate because the same street name recurs across cities. It stops short of naming alternatives (e.g. when to call search_localities first to resolve an id), so it lacks full when-not guidance.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description's genuinely additive piece is the Argentina coverage limit, but it does not disclose whether an out-of-coverage point yields an error, null, or empty result — the main behavioral unknown for this 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?

Two sentences, no filler, with the core operation front-loaded and the coverage caveat immediately after. Every sentence earns its place.

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, the description correctly assumes responsibility for naming the returned fields (province, department, municipality). What remains uncovered is failure behavior outside Argentina, which an agent would need to handle the common error path.

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 ranges and example values already documented, so baseline would be 3. The description adds the coordinate datum (WGS84), which is real information the schema does not state and matters for correct input formatting.

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 uses a specific verb+resource pairing ("find the province, department and municipality that contain a WGS84 point") and names the three administrative levels returned. This is immediately distinguishable from the sibling search_* tools, which are forward lookups rather than point-in-polygon resolution.

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?

"Only points inside Argentina resolve" gives a clear scope boundary that tells the agent when this tool will not work, which is strong usage context. It stops short of naming alternatives (e.g., use normalize_address for street addresses) or stating what to do for out-of-scope coordinates.

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?

The annotations (readOnlyHint: true, destructiveHint: false) already provide robust safety information. The description adds the specific scope of the data (local administrative divisions), which is contextually helpful.

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 extremely concise, managing to convey the 'what' (search departments), the 'how' (by name/province), and the 'where' (Buenos Aires/CABA context) in a single, efficient sentence.

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 that the annotations cover safety and the schema covers data constraints (max results), the description is complete. It adds critical regional nuance that the structured fields cannot convey.

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 description provides no novel semantic information. It successfully lists the main search targets ('name and/or province'), but this is largely covered by the 'nombre' and 'provincia' fields in 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?

The description explicitly states the tool's purpose: 'Search departments'. It also provides extremely valuable context regarding specific regional names (partidos in Buenos Aires, comunas in CABA), which distinguishes it from generic geographical searches.

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?

It clearly lists the criteria for searching ('by name and/or province'), which guides the user on how the search function works. It is implicitly distinct from sibling tools because of its focus on 'departments' rather than 'provinces' or 'localities'.

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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds the dataset provenance, which is mild context, but says nothing about result truncation, ranking, or matching behavior (exact vs partial name match).

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 the resource, source dataset, primary key, and optional filters; no wasted words.

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 4-parameter read-only search with full schema coverage and no output schema, the description covers what the tool does and its filter scope. The only real gap is sibling disambiguation against search_municipalities.

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 examples for nombre and provincia, so the schema does the heavy lifting. The description only restates the name/province/department filters and omits the 'max' result-count parameter entirely, adding little beyond structured fields.

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 (search) and resource (localities), and disambiguates the resource as cities/towns/settlements from the BAHRA dataset. It does not differentiate from the very similar sibling search_municipalities, which an agent would need to choose between.

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?

"Optionally within a province and department" implies when the filter parameters are useful, but there is no explicit guidance on when to use this rather than search_municipalities or search_departments, nor any prerequisites.

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?

Annotations already provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond the search fields themselves — no mention of result limits, pagination, or what happens when filters are omitted.

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 core action and its filter dimensions come first.

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, fully annotated, zero-required-parameter search with no output schema, the definition is largely sufficient. The one meaningful gap is routing guidance against its three sibling search tools, which the description doesn't address.

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 each parameter (max, nombre, provincia) is already documented with examples and bounds. The description only echoes the name and province filters and omits the max limit, so it adds no meaning beyond the schema. 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 ('Search municipalities') and clarifies scope with '(local governments)'. However, it offers no differentiation from the closely related search_provinces, search_departments, and search_localities siblings.

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 a name/province lookup but never states when to use this tool versus the sibling search tools, nor any prerequisites or exclusions. An agent must infer the routing decision from names alone.

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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine value by disclosing the return fields (official name, INDEC id, centroid) and the list-vs-filter behavior. Pagination/ordering remains undisclosed, which keeps it below a 5.

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?

Three short sentences, front-loaded with scope, then the filter behavior, then the return payload. No filler whatsoever.

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 only two optional parameters, full annotation coverage, and the return fields spelled out in the description (no output schema exists), an agent has everything needed to call it correctly. Minor omission: no statement of ordering or how max interacts with the 24-item result set.

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 baseline is 3. The description adds meaning beyond the schema by explaining the consequence of omitting nombre (returns the full list) and indicating that name matching is accent-tolerant is reinforced in the schema example.

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 with precise scope: "Search Argentina's 24 provinces (including CABA) by name." The resource granularity (provinces vs. departments/municipalities/localities in the sibling set) makes it distinguishable without opening the schema, though no sibling is named 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?

"Omit nombre to list them all" gives clear operational guidance for the two modes of use. There is no explicit statement of when to prefer this over search_departments or search_localities, so it falls short of full alternatives coverage.

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