Retrieve Shapes for Known loc_ids

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

Annotations already indicate readOnly, idempotent, and non-destructive, and the description adds meaningful context beyond them: the default fast preflight returns has_shape, shape metadata, centroid, and bounding box, while include_polygon=true is needed only for GeoJSON coordinates. It also discloses that historical geometry is returned first and successors are never substituted automatically, plus 'No payment required.' There is no contradiction with 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 purposeful, with the core purpose and usage guidance front-loaded before the return behavior and sibling routing. Every sentence contributes useful information, though a small amount of redundancy exists between the opening 'exact loc_ids or parent+admin_level' condition and the later Admin Spine versus exact loc_ids distinction. It is appropriately sized for a tool with this much routing nuance.

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 complexity — three mutually exclusive input modes, a nested scope object, an optional polygon flag, and an output schema — the description covers what an agent needs to invoke it correctly. It explains default behavior, the polygon flag's purpose, sibling boundaries, and the no-payment requirement. The output schema handles return-value details, so no major information gap remains.

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 high (83%), so the schema already documents parameters like loc_id, loc_ids, scope, and include_polygon. The description adds useful meaning by clarifying the default response when include_polygon is false and by mapping user intent (exact loc_ids vs. admin parent+level) to the relevant input modes. This goes beyond the schema's basic parameter descriptions without being redundant.

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: it retrieves shape availability and bounded coordinates for known loc_ids or an admin scope. It explicitly distinguishes itself from get_loc_id_info, which covers hierarchy, identity, catalog coverage, and crosswalk facts. The title and description align, leaving no ambiguity about 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 states exactly when to use the tool: when you already have exact loc_ids, or one administrative parent_loc_id plus target admin_level. It explicitly names the alternative, get_loc_id_info, for hierarchy and identity needs, and clarifies that get_geometry does not return those place details. It also notes that administrative scope queries use the Admin Spine layout while independent geometry families require exact loc_ids, giving the agent strong routing guidance.

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