Ziplore: US ZIP Code API (county, time zone, demographics, radius)

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

Annotations already carry the full safety profile (readOnly, openWorld, idempotent, non-destructive), so no contradiction exists. The description adds one behavioral detail beyond them — population-descending sort order — which is genuinely useful. However, it does not mention default limit behavior or output shape.

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 tight sentence with zero filler. The core purpose is front-loaded and the ordering nuance is appended efficiently.

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 list-returning tool with strong annotations and no output schema, the description covers purpose and sort order. Gaps remain: limit semantics are left to the schema, state disambiguation is implied, and no mention of result size defaults — but these are minor for a straightforward lookup.

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 only 33% (only 'state' is documented in the schema). The description adds 'US' context and ordering, which weakly relates to state and limit, but it does not explain what 'limit' caps, when 'state' is needed, or how city/state interact for disambiguation. With low coverage, the description under-delivers on compensating for the undocumented parameters.

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?

Description states a specific operation ('All ZIP codes of a US city') with a distinguishing detail ('largest population first'). The verb+resource combination clearly separates it from siblings like nearest_zip, zip_lookup, and zips_in_radius, which are different operations entirely.

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 purpose implies when to use it (listing all ZIPs for a city), and the sibling names make the alternatives evident, but there is no explicit 'use this when / use that instead' guidance or exclusions. An agent must infer the boundary 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 readOnlyHint, idempotentHint, and non-destructive behavior, so the description's burden is lower. It adds that the tool returns ZIP code(s) and distance, but does not clarify units or how multiple results are handled. It does not contradict 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?

A single, front-loaded sentence with no fluff. It states the core action and output concisely, making it easy 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 tool with three parameters and no output schema, the description is minimal. It lacks details on the output structure, distance units, and the meaning of count. While annotations cover safety, an agent would need to guess on how to interpret the response, which is a notable gap.

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 description mentions 'latitude/longitude' which maps to lat and lon parameters, but it does not explain the 'count' parameter at all. Since schema coverage is 0%, the description should clarify count's role (e.g., number of nearest ZIPs to return), which it omits. Minimal added value 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 clearly states the tool performs reverse geocoding from latitude/longitude to nearest US ZIP code(s), with distance. It distinguishes from siblings like zip_lookup (which likely takes a ZIP code) and zips_in_radius (which takes a radius), making its purpose specific and 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?

There is no guidance on when to use this tool versus alternatives. It does not mention scenarios like 'use when you have coordinates and need ZIP' or contrast with zip_distance or city_zips. The agent must infer usage from the name and description alone, which is insufficient.

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 indicate read-only, idempotent, non-destructive behavior. The description adds context beyond annotations by specifying the algorithm (great-circle) and output units (miles and km), which is useful behavioral detail not captured by the structured fields.

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, concise sentence that front-loads the core action and output. No extraneous information, and it effectively covers the essential purpose in minimal 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 simplicity (two required string parameters, no output schema), the description is nearly complete: it states inputs and outputs. It does not mention edge cases like invalid ZIP codes or approximation errors, but these are minor for a straightforward distance calculator.

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%, so the description must compensate. It clarifies that 'from' and 'to' are US ZIP codes, adding meaning beyond the bare string type. However, it does not specify format (e.g., 5-digit vs 9-digit) or ordering, leaving some ambiguity.

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 computes great-circle distance between two US ZIP codes, with output in miles and km. This is a specific verb-resource pair that distinguishes it from siblings like nearest_zip or zips_in_radius, which serve different purposes.

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 does not explicitly mention when to use this tool versus alternatives, nor does it reference any sibling tools. However, the purpose is self-evident enough that an agent can infer usage for distance between two specific ZIPs, but there is no explicit guidance or exclusion criteria.

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, and destructiveHint=false, covering the safety profile. The description adds input flexibility (ZIP+4, addresses, missing leading zero) but does not disclose additional behavioral traits such as rate limits, permission requirements, or output variability. Since annotations already cover the core safety, this is adequate but not rich.

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, well-structured sentence that front-loads the main purpose and then lists the key output fields. There is zero redundancy, and every phrase contributes meaning. The format is clear and easy 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 tool with no output schema and two parameters (one optional), the description provides a comprehensive list of return fields, input flexibility, and the purpose. It is missing explicit clarification on the demographics boolean's behavior, but the overall information is sufficient for an agent to call the tool correctly and understand the expected output.

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 50%: the 'zips' parameter is fully described in the schema, while 'demographics' has no schema description. The description mentions 'Census demographics' as part of the output, which gives partial meaning to the demographics flag, but it does not explicitly explain what the boolean toggles or its effect on the response. It adds some value beyond the schema but doesn't fully compensate for the uncovered parameter.

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 a specific verb (look up) and resource (US ZIP codes), and enumerates the exact fields returned (city, state, county, FIPS, coordinates, time zone, demographics). This distinguishes it from siblings like nearest_zip or zip_distance, which perform different operations. The purpose is unambiguous and specific.

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 usage when you have ZIP codes and need their details, but it does not explicitly differentiate from the sibling tools or state conditions for when to choose this tool over alternatives. It doesn't mention exclusions like 'use nearest_zip for location-based queries.' The context is clear but not explicit.

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 safe, read-only, idempotent behavior. The description adds the ordering (closest first) and that distance in miles is returned. However, it omits the limit parameter behavior (default 25, max 50), implying 'Every US ZIP' even though results are capped. This is a meaningful behavioral gap for an agent to know.

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, front-loaded sentence that conveys the core operation and key output detail. There is no verbosity or redundancy; every phrase contributes to understanding.

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 five parameters and no output schema, the description is reasonably informative but incomplete. It lacks information about the result cap (limit), does not specify that a center point is effectively required despite schema allowing only miles, and does not describe any pagination or additional output fields beyond distance. An agent would need to infer or experiment to fully use it.

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. It explains 'miles' as the radius and that the center can be a ZIP or lat/lon. However, it does not explain the 'limit' parameter or clarify that either zip or lat/lon should be provided (only miles is required in schema). It partially covers the parameter semantics but misses key details.

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 function: return every US ZIP within N miles of a center point (ZIP or lat/lon), sorted closest first, with distance included. It is specific about the resource and behavior, and the phrase 'Every US ZIP' distinguishes it from siblings like nearest_zip (returns a single one) and zip_distance (calculates distance between two given points).

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 explicit guidance on when to choose this tool versus siblings such as nearest_zip or zip_lookup. It does not mention scenarios, exclusions, or alternatives. The purpose is clear, but the usage context 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.