CodePostalPro

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral limits: NANPA rate centres are matched to cities, so results are city-level rather than legal boundaries, and mobile numbers keep their code after moving. This is precisely the kind of non-obvious context an agent needs before relaying results.

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 sentences cover output contents, usage examples, and caveats with no filler. The most decision-relevant information (what the tool returns) is front-loaded, and the caveat is explicitly marked for the agent to relay.

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 one-parameter, read-only lookup with no output schema, the description covers all essential context: input semantics (via schema), return contents, accuracy caveats, and indirect sibling routing. Nothing an agent needs to invoke or explain this tool is 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?

The single parameter is fully described in the schema ('Three-digit NANPA area code, e.g. "310"'), so the description need not repeat it. It adds example query strings, but no additional format or validation semantics beyond 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 states exactly what the resource yields — serving state(s), top cities by ZIP count, total ZIP/city counts, and overlay_codes — and anchors it with concrete queries like 'where is area code 310' and 'what area code is Denver'. This clearly differentiates it from siblings such as lookup_postal_code, which handles postal-code geography rather than area-code geography.

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 gives explicit when-to-use triggers ('where is area code 310', sanity-checking a phone number’s geography) and a clear routing hint for city-to-code questions ('via the city’s ZIPs instead'). It does not name the sibling tool explicitly, so the agent must infer that lookup_postal_code is the alternative.

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=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about the return content (complete list of ZIP codes, coordinates, time zone, area codes), which is useful beyond the annotations. No contradiction.

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 two sentences, front-loading the core return value and then the input requirements. It is efficient with no fluff, though the first sentence is somewhat long with the enumeration of country-specific terms.

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 no output schema, the description explains what the response contains (all localities/ZIP codes, and for US cities the complete list with coordinates/time zone/area codes). It also explains how to obtain the required slugs. This is sufficient for an agent to call the tool correctly, though it could mention pagination or limits if any.

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 0% with no descriptions for any parameter. The description explains that region and group are slugs (from get_region), but does not clarify the country parameter format (e.g., code vs name). This partially compensates for the schema gap but leaves one parameter ambiguous.

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 clearly states the tool returns a geographic group (city/district) with all its localities/ZIP codes, and specifies the complete ZIP code list for US cities. This is a specific verb+resource, and while it doesn't explicitly name a sibling alternative, the content is distinct from the sibling tools like lookup_postal_code or get_region.

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 provides a prerequisite (needs region slug and group slug from get_region) but does not explicitly state when to use this tool versus alternatives. It implies usage when you have slugs and need full locality data, but doesn't mention exclusions or alternatives.

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 the operation as read-only, idempotent, and non-destructive, so the description does not need to restate that. It adds useful context about the returned data, but it does not disclose behavior for missing regions, invalid country values, or whether the country parameter must be a slug or display name.

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 sentences, each earning its place: the first defines the resource and its contents, the second explains downstream usage, and the third clarifies slug formatting. It is front-loaded and free of 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?

With no output schema, the description carries the burden of explaining return values, and it does describe names, slugs, postal codes, and area codes. However, it omits guidance on the 'country' parameter, possible empty results, and slug source or validation, leaving an agent uncertain in non-standard cases.

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 only 50%: 'region' has a description but 'country' does not. The description compensates well for 'region' with slug format and examples ('texas', 'ile-de-france', 'alger'), but it leaves the 'country' parameter entirely unexplained, so the agent still lacks complete parameter semantics.

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 clearly states what the tool returns: a region with its cities/départements/delegations, including names, slugs, postal codes, and US area codes. This is specific and goes beyond the tool name, though it does not explicitly differentiate itself from sibling tools like area_code_lookup.

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 useful guidance on how to use the returned slugs ('Use the slugs it returns to call get_group or get_place'), which implies a follow-up workflow. However, it does not state when to choose this tool over alternatives such as search_places, list_countries, or lookup_postal_code.

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 read-only, idempotent, non-destructive behavior; the description adds meaningful scope details: exactly what country facets are returned, the split between curated and GeoNames entries, and the instruction to call it once. This goes beyond the annotation safety profile and clarifies the tool's output content.

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 tightly packed sentences lead with 'Coverage overview' and enumerate the specific data categories without filler. Every phrase adds useful information, and the use-case guidance is included without bloating the text.

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 read-only tool with no output schema, the description is complete: it tells the agent what data will be returned, names the data source, and explains when to invoke it. Nothing needed for correct invocation is 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?

The input schema has zero parameters)Skip, so no parameter documentation is needed. The description correctly implies that calling requires no arguments and focuses on the return content instead. This meets the baseline for a no-parameter tool.

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 clearly states the tool is a coverage overview of countries, enumerating the eight curated countries' data fields and the bulk_tier of ~115 additional GeoNames countries. This distinguishes it from the sibling lookup/search tools by targeting coverage checking rather than postal-code or region operations.

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 explicitly says to call the tool 'once if unsure whether a country is covered,' which gives a clear when-to-use condition. It does not name nearby alternatives or state when not to use it, but the coverage-checking purpose is sufficiently distinct from the sibling 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context: the verification status values, the conflict handling rule ('never pick one silently; tell the user both'), the tier distinction between curated and bulk records, and the fact that bulk records lack demographics. This goes well beyond the annotations.

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 dense but well-organized: it front-loads the core purpose, then details the return fields, then coverage tiers, then conflict handling. Every sentence adds information. It is longer than average, but the length is justified by the tool's rich output and the need to explain the curated vs bulk distinction. Slight redundancy with the schema's country description, but not enough to lose a point.

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 read-only lookup tool with two fully documented parameters and no output schema, the description is remarkably complete. It explains what fields come back, how to interpret verification status, how to handle conflicts, and what to expect for different countries. An agent can call this tool correctly and interpret its results without additional context.

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 both parameters. The description adds value by giving concrete examples ('90210', '75001', '16000') and clarifying that the code should be 'exactly as written'. It also explains the country parameter's ISO alpha-2 format, though the schema already states that. The description doesn't add much beyond the schema, but the examples and exact-match guidance are useful.

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 ('Look up') and resource ('postal code or US ZIP code'), and enumerates the exact fields returned. It distinguishes itself from siblings like area_code_lookup and nearby_places by clarifying it returns localities, time zones, area codes, and demographics for a postal code.

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 explicitly explains when to use this tool (lookup by postal/ZIP code) and contrasts it with the sibling area_code_lookup by noting it returns US telephone area codes as part of the record. It also gives coverage guidance: curated full records for specific countries, bulk-tier records for others, and instructs the agent to tell the user both values on conflict rather than silently picking one.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond this: results are sorted nearest-first, each includes distance_km, and distances are measured to the locality centroid from source data, not to a boundary. This clarifies an important semantic that would otherwise be unknown.

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 three sentences with no wasted words. The core action is front-loaded, followed directly by example use cases and a single important caveat about centroid-based distances. 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?

For a read-only lookup tool with no output schema, the description covers the essential usage scenarios, result ordering, and a key distance-calculation caveat. It does not describe the full response shape beyond the presence of distance_km, but with readOnly/idempotent annotations and clear examples, an agent has enough context to invoke the tool 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 60%, so the schema already describes `limit`, `country`, and `radius_km`. The description adds meaning for `lat` and `lon` as the center point of the search, and hints at `radius_km` via the 'within 10 km' example. However, it does not clarify parameter names or ranges beyond what the schema provides, nor does it explain how `country` or `limit` interact with the result ordering.

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 clear, specific action: 'List localities around a latitude/longitude, nearest first, each with `distance_km`.' It also gives example intents like 'postal codes within 10 km of...' and resolving coordinates to the closest postal code. It does not explicitly name a sibling tool as an alternative, but the action and expected output are unambiguous enough to distinguish it from the provided sibling tools.

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 provides explicit use-case examples ('what ZIP codes are near...', 'postal codes within 10 km of...', 'resolve coordinates to the closest postal code') that tell an agent when to invoke this tool. It lacks explicit when-not-to-use guidance or named alternatives, but the examples are sufficient to select this tool over the siblings in most relevant scenarios.

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=true and idempotentHint=true, covering the safety profile. The description adds valuable behavioral context beyond that: 'Results are ranked exact-name-first, then by population' and that non-curated countries 'searches the bulk GeoNames tier.' These behaviors are not present in the annotations or schema, so the description meaningfully enhances transparency without contradicting anything.

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 three sentences, front-loaded with the core purpose, then layered with usage guidance, ranking behavior, and country restrictions. Every sentence adds distinct value—no filler or repetition. It is compact yet comprehensive, ideal for an agent to parse quickly.

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 read-only search tool with no output schema, the description covers all essentials: what it searches, ranking order, the exact relationship to a sibling (same records as lookup_postal_code), and the country-tier nuance. An agent can confidently call this tool with the right parameters and interpret the result, given the reference to lookup_postal_code. Nothing critical is 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 description coverage is 100% (all three parameters have descriptions). The description adds contextual meaning beyond the schema: it explains that 'query' can be a place name or postal-code prefix (though the schema says this too), and critically provides guidance on when and why to use 'country' ('names repeat across countries'), which is not in the schema. This extra behavioral nuance justifies a 4 rather than the baseline 3.

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 clearly states the tool's purpose: 'Find localities by name, city name, or the beginning of a postal code.' It uses a specific verb ('find') and resource ('localities'), and explicitly contrasts itself with lookup_postal_code by noting it handles partial codes and names. It also differentiates from nearby_places by focusing on postal-code association rather than proximity. This makes its role 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?

Provides explicit when-to-use guidance: 'Use this when the user gives a place name and wants its postal code(s), or has a partial code.' It also offers a clear alternative: 'Returns the same full records as lookup_postal_code,' implying that for exact code lookup, the sibling should be used. Additionally, it instructs to restrict with 'country' whenever known and explains the rationale (name repetition), plus notes the bulk tier behavior for non-curated countries. This fully equips an agent to select the right tool.

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