CodePostalPro

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

With no annotations provided, the description carries the full burden and handles it well: it explains overlay_codes, the rate-centre-to-city matching, the non-legal-boundary caveat, and mobile-number portability. This goes well beyond a simple 'looks up area codes' statement.

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 into three sentences: output fields, use cases, and caveat. Each sentence adds substantive information without filler, and the parenthetical overlay example makes the abstract concept concrete.

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?

The tool is simple—one required string parameter and no output schema—so the description's list of returned fields (states, top cities, ZIP/city counts, overlay_codes) is sufficient. It also includes the key caveat about city-level accuracy, making the tool safe and predictable to invoke.

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 already fully describes the only parameter as a 'Three-digit NANPA area code' with an example, so the description doesn't need to add much. It reinforces that this is a US/NANPA code and provides usage examples, but doesn't introduce new parameter-level constraints.

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, well-scoped resource—US telephone area codes—and enumerates the exact output: states served, top cities by ZIP count, total ZIP/city counts, and overlay_codes. Use-case examples like 'where is area code 310' make the tool's goal unmistakable, and the 'via the city’s ZIPs instead' phrasing helps separate its role from a postal-code-style 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 explicitly says 'Use it for' and provides concrete query types, plus a sanity-check use case. It does not name a specific sibling tool or an explicit when-not-to-use condition, but the ZIP-based aside implies the alternative route. The Denver example is slightly indirect since the tool takes an area code, not a city.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It does disclose meaningful output behavior, such as the complete ZIP-code list for US cities with coordinates, time zone, and area codes. However, it does not mention whether the operation is read-only, what the response shape looks like, or any error/availability considerations.

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 front-loaded with the core subject and content, then moves to parameter sourcing. It is reasonably concise, though the first sentence is dense and 'ZIP codes' appears twice, creating mild redundancy without padding.

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 tool with no output schema and no annotations, the description covers the key facts an agent needs: what the group represents, what data is included, and where to get the required slugs. It is not exhaustive—country semantics and response shape are missing—but it is sufficient for correct invocation in most 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 description coverage is 0%, so the description must compensate. It explains that region and group are slugs sourced from get_region or record fields, which adds real meaning beyond the bare schema. However, the country parameter's format and accepted values are not explicitly described, leaving the compensation incomplete.

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 identifies the resource as a city/département/province/post office/delegation and states what it contains: all localities/ZIP codes. It differentiates the tool from siblings like get_region and lookup_postal_code by describing the group-level output. It lacks an explicit verb such as 'returns', but the intent 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 clear invocation context by stating that region and group slugs are required and where to obtain them ('both from get_region or from any record's region.slug / group.slug'). It does not explicitly state when not to use this tool or name alternative sibling tools, so it stops short of a 5.

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 burden of behavioral disclosure. It adds useful details beyond the schema, such as the slug format examples and US-specific area code behavior. But it does not mention edge cases, error handling, or whether any side effects exist, though the tool appears to be a read operation.

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 output content, the downstream usage, and the slug format. Information is front-loaded and there is no filler or repetition.

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?

The description explains the returned data and slug conventions, which is helpful for a two-parameter tool with no output schema. However, the required 'country' parameter is not defined, and error or invalid-input behavior is absent, leaving meaningful gaps for correct invocation.

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 documents only 'region' as 'Region slug' (50% coverage). The description enriches the region parameter with lowercase-hyphenated format and examples, but leaves the 'country' parameter completely unspecified beyond an implicit US reference. This is partial compensation for the coverage gap.

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 defines the tool as returning a region (state, région, wilaya, governorate) with its subdivisions, slugs, postal codes, and area codes for US states. It also references get_group and get_place, helping distinguish it from sibling tools like area_code_lookup and search_places.

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 a clear downstream usage instruction ('Use the slugs it returns to call get_group or get_place') and implies the tool is for retrieving region-level data. However, it does not explicitly state when to choose this tool over siblings like area_code_lookup, nor does it provide exclusions or alternative conditions.

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 must fully convey behavior. It states the contents returned and implies an idempotent read via 'call it once,' but it does not explicitly confirm read-only semantics, output formatting, or data freshness. For a simple parameterless list, this is minimally sufficient but not comprehensive.

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 concise sentences: the first enumerates the exact content returned, the second provides a clear usage recommendation. There is no filler, redundancy, or unnecessary detail.

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 no-parameter list tool without an output schema, the description adequately specifies what data will be returned and when to invoke it. Minor omissions like ordering, count, or update cadence are not critical for the stated purpose.

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 has zero parameters, so the schema imposes no burden. The description adds meaningful context about what the tool returns, which aligns with the baseline of 4 for parameterless tools.

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 identifies the tool as returning the list of covered countries with postal-code format, hierarchy labels, key facts, and time zones. The resource and scope are evident, though the lack of an explicit verb like 'lists' makes it slightly less direct. It does not strictly contrast with sibling tools, but the country-coverage focus makes its purpose distinct.

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 instruction 'Call it once if unsure whether a country is covered' gives an explicit condition for use and implies this is the go-to tool for coverage checks. It does not mention alternatives or exclusions, but the guidance is clear enough for routing an agent.

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 provided, the description carries full weight and does so excellently. It discloses the full return shape, the verification statuses, and the critical conflict-handling rule: never pick a conflicting code silently, tell the user both. This goes well beyond the structured schema.

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 front-loaded with the main purpose. The long second sentence enumerates return fields that are necessary because no output schema exists. Every clause earns its place, though it could be slightly better organized.

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 tool with two simple parameters, no output schema, and no annotations, the description is remarkably complete. It explains the geographic coverage, the structure of results, data provenance, verification semantics, and how to handle conflicts. Nothing essential is missing for correct invocation.

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 baseline is 3. The description adds minor value by explaining 'US ZIP code' and giving examples like '75001' and '16000', but the schema already documents both parameters clearly and completely.

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 opens with a specific verb and resource: 'Look up a postal code or US ZIP code.' It clearly defines what is returned and is unambiguous against sibling tools like area_code_lookup and nearby_places, even without naming them.

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 clearly implies when to use the tool: whenever a postal/ZIP code needs resolving for the listed countries. However, it does not explicitly state when not to use it, nor does it name alternatives such as area_code_lookup for telephone area codes.

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 provided, the description carries the full burden for behavioral disclosure. It clearly states the output is ordered by distance, includes distance_km, and adds a non-obvious caveat that distances are to the locality centroid, not the boundary. This is valuable context beyond the schema.

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 that front-load the core action and output, then provide examples and a crucial caveat. There is no redundancy or filler; 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 tool with no output schema and no annotations, the description covers the input coordinates, output field, ordering, and an important distance caveat. It does not explicitly state default parameters, but the schema covers limit and radius_km defaults, and it does not describe no-result behavior, but overall it is sufficiently complete for correct invocation.

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 60%, with lat and lon lacking descriptions. The description clarifies that lat/lon define the center point and that the search radius in the examples maps to radius_km. It also explains the significance of the first result, adding meaning beyond the raw parameter definitions.

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 ('List'), a clear resource ('localities around a latitude/longitude'), and the output field ('distance_km'), with an ordering constraint ('nearest first'). The example use cases make it easy to distinguish this from siblings like search_places or lookup_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 names when to use the tool ('what ZIP codes are near…', 'postal codes within 10 km of…', 'resolve coordinates to the closest postal code'). It does not explicitly mention when not to use it or alternative tools, but the context is clear enough to guide an agent's selection.

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 discloses the ranking behavior (exact-name-first, then by population) and that it returns the same full records as lookup_postal_code. It does not mention rate limits, auth, or side effects, but these are absent for a search tool; the described behavior is sufficient for an agent to anticipate outputs accurately.

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 concise (about 50 words) and front-loaded with the core purpose. Every sentence adds value: the first explains what and when, the second provides ranking details, and the third gives a crucial usage tip. 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?

Given the tool's moderate complexity, the description fully covers how to invoke it correctly: supported inputs, required parameter, constraints (minimum length), and output type. The ranking behavior and the hint about country are useful context. With no output schema, the mention that it returns the same records as lookup_postal_code is sufficient.

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 already documents all parameters with descriptions, achieving 100% coverage. The description adds semantics for `query` by clarifying that it can be a partial postal code, and for `country` by stressing its importance. However, this adds marginal value over the schema, so a baseline 3 is appropriate.

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: finding localities by name, city, or postal-code prefix. It names specific inputs (place name, city, postal code) and outputs (postal codes), distinguishing it from siblings like lookup_postal_code by its focus on searching by name or prefix. This makes it easy for an agent to understand what the tool does.

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 guidance on when to use the tool: when a user gives a place name and wants postal codes, or has a partial code. It also gives a clear directive to restrict with `country` when known, explaining why (names repeat across countries). This covers both when to use and how to use effectively.

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