DaedalMap Administrative Boundaries (loc_id to polygon)

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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable context beyond that: it is 'fast' and 'shape-only' indicating no actual geometry is returned, explicitly states it does not resolve points or identity relationships, and notes 'No payment required.' This gives the agent a clear picture of behavioral limitations and costs.

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 concise sentences that front-load the core action and outcome. Every sentence contributes useful information (what it does, what it does not do, when to use it, payment status) without redundancy or fluff.

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 simple preflight nature, the description covers what it returns ('whether... has reusable geometry and its geometry vintage'), what it excludes, and when to use it. No output schema exists, but the return content is summarized sufficiently for an agent to decide invocation and interpret the result.

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 parameters are already well-documented. The description adds some context by clarifying the loc_id/loc_ids relationship as 'one or a bounded list,' but it does not significantly go beyond the schema details. 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 is a 'Fast shape-only preflight' for one or more loc_ids, and specifies what it reports (geometry availability and vintage). This clearly distinguishes it from get_geometry (which retrieves geometry) and other sibling tools by emphasizing it is a preflight check.

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 before get_geometry or an export,' providing direct guidance on when to use this tool relative to alternatives. It also notes what the tool does NOT do ('does not resolve points or explain identity relationships'), which helps exclude inappropriate use cases.

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 only mark readOnlyHint true, but the description adds valuable behavioral context: it returns results only 'when approved geometry exists', includes 'N-way successor context', and mentions that 'no payment required'—implying some external cost or authorization check. It does not contradict annotations and adds nuance beyond the simple read-only flag.

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 four sentences, front-loaded with the purpose, then outputs, then usage context, then caveat and payment note. Every sentence adds distinct information with no filler, making it appropriately sized and structured.

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 and lack of an output schema, the description covers key invocation context: when to use, what it returns, and a condition ('when approved geometry exists'). It does not explain what 'approved geometry' means or how to interpret 'N-way successor context', but it provides enough for an agent to select and call the tool appropriately.

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 mentions 'temporal validity' in outputs, which loosely ties to as_of parameters, but it does not add specific meaning to parameters like left_loc_id, include_successors, or batch_id. The schema itself already describes each parameter clearly.

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 it is a 'Detailed relationship tool for two geographic identities' and enumerates specific outputs: 'temporal validity, N-way successor context, topology, geodesic intersection area, and directional overlap shares'. This distinguishes it from siblings like get_geometry or loc_id_info, which focus on single identities.

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?

Explicit guidance is given: 'Use this after a compact point lookup when the caller asks whether two tiers/releases really contain or overlap one another' and 'Use resolve_reference first for names or outside identifiers.' This tells the agent when to use the tool and when to use an alternative, plus the caveat that 'a point-chain seam is not proof of strict parentage.'

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 description discloses important behavioral traits beyond the readOnlyHint=false annotation: it is synchronous, has a size constraint and response-time budget on hosted service, and behaves differently for local loopback callers (no cap). These details inform the agent about operational limits and execution mode, adding substantial context beyond the annotation.

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 adding constraints and alternative guidance. Every sentence earns its place; there is no redundancy or 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?

For a tool with 8 parameters, nested scope object, and no output schema, the description provides essential context: purpose, input modes, output formats, operational limits, and pointer to alternatives. It lacks explicit detail on scope object semantics and some optional parameters, but the schema provides partial descriptions, and the missing info may be non-critical for selection/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 description adds meaning beyond the schema by clarifying that loc_id, loc_ids, and scope are alternatives ('exact loc_ids or one strict scope') and by listing the output formats that map to the format enum. It also highlights the loc_ids limit. However, with only 38% schema coverage, it does not explain scope sub-properties, include_polygon, or output_name semantics, leaving some 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 begins with a specific verb ('Creates'), names the resource ('geometry export'), specifies input modes ('exact loc_ids or one strict scope'), and explicitly lists output formats ('GeoJSON, gzipped GeoJSON, or zipped GeoJSON'). This clearly distinguishes it from sibling tools like get_geometry or get_pack by emphasizing creation of an export rather than retrieval.

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 concrete guidance on when to use this tool versus alternatives: it states the hosted-service cap (250 loc_ids, 10-20 second response budget) and explicitly directs users to estimate_geometry_package or get_tool_help for determining the effective access lane. This is clear context for choosing this tool over siblings.

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 the description aligns by framing the operation as an estimate. It adds context beyond the annotation by enumerating what the estimate includes (loc_id count, shape/vintage availability, bytes, delivery mode, citation requirements, charge units) and by clarifying that it is not a canonical release bundle. This provides meaningful behavioral transparency without contradicting 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 two sentences, front-loaded with the core action ('Dry-run estimate') and packed with specific output details. Every clause adds value, with no redundancy or 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?

The tool has 7 parameters and a nested object, but the schema handles parameter detail well. With no output schema, the description compensates by listing exactly what the estimate covers. It also clarifies the artifact boundary (not a canonical bundle). The only minor gap is not explicitly mentioning the three mutually exclusive input selectors (loc_id, loc_ids, scope), but the schema's anyOf provides that 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 86%, so the schema already explains most parameters. The description adds no additional parameter details; it only names the tool's purpose. Baseline of 3 is appropriate because structured data carries the semantic load, and the description does not need to compensate.

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 ('estimate') and resource ('geometry export'), and clearly distinguishes this from actual creation by calling it a 'dry-run'. It also explicitly differentiates from 'canonical DaedalMap geometry release bundle', setting it apart from sibling tools like get_geometry and create_geometry_export.

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 'dry-run estimate' phrasing implies this tool is used before a real export, but the description does not explicitly state when to use it versus create_geometry_export or other alternatives. No exclusions or alternative tool names are provided, leaving usage to be inferred rather than directed.

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 declare readOnlyHint=true, so safety is covered. Description adds 'Free discovery' implying no cost/limits and 'live' implying freshness. However, no mention of pagination or output size limits, and no output schema to clarify return structure.

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?

Single sentence with key info front-loaded ('Free discovery'). No fluff.

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 zero-parameter read-only tool, the description provides sufficient context: what is returned and from where. Could mention if the list is exhaustive or paginated, but overall adequate.

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?

No parameters; schema coverage is trivially 100%. Description adds no param info needed.

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 clearly states verb (returns) and resource (list of live agent-ready data packs on DaedalMap). Distinguished from siblings: 'get_boundary' suggests boundaries, 'get_pack' suggests single pack, 'loc_id_info' suggests location data.

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?

No explicit when-to-use or when-not-to-use vs alternatives. 'Free discovery' hints at lightweight use, but lacks formal guidance. Adequate for a simple tool but could be more directive.

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 readOnlyHint true, the description adds valuable context beyond the annotation: it lists return contents (metadata, vintage, centroid, bounding box, optional polygon) and mentions 'No payment required.' It also discloses a limitation (does not explain hierarchy). These are useful behavioral insights without contradicting the annotation.

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 focused sentences, front-loaded with the core purpose ('Shape retrieval for exact loc_ids'). Every clause earns its place: scope, return values, alternative tool, usage preference, and payment note. No redundancy.

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 tool with complete schema descriptions and readOnlyHint annotation, the description covers the essential aspects: what it retrieves, what it returns (including optional polygon), its limitations, and when to use alternatives. No output schema exists, but the description sufficiently outlines return components. It is contextually complete.

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 adds minimal parameter-specific semantics beyond the schema: it references 'optional GeoJSON polygon' (tied to include_polygon) and advises preferring bbox/centroid, but does not elaborate on batch behavior or format. This is sufficient but not additive 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 retrieves geometry ('Shape retrieval') for specific loc_ids, and explicitly distinguishes it from loc_id_info by noting it does not explain hierarchy or crosswalks. It also specifies the scope (exact loc_ids and resolve_point chain levels), making its purpose 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?

Explicitly provides when to use alternatives: 'It does not explain hierarchy or crosswalks; use loc_id_info for those details.' Also gives a clear preference rule: 'Prefer bbox/centroid unless exact rendering or clipping requires the polygon.' This is strong usage 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?

The read-only annotation is complemented by the description's clarification that only completed inline jobs are retrievable, and that queued jobs or artifact links are not yet available. This adds practical expectations for callers.

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 deliver purpose and limitations clearly, with no wasted words. The first sentence is immediately actionable, and the second provides necessary context without bloat.

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?

Although no output schema exists, the description is sufficient for a simple retrieval operation, covering what is retrieved and noting what is not available. It does not describe the response structure or error behavior, but these are less critical given the tool's simplicity.

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 both job_id and request_id, so the description adds no new parameter semantics. It only restates job_id as a lookup key, which is redundant with the schema's 100% coverage.

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 action: retrieving a completed geometry export or conversion job by job_id. Its focus on job retrieval distinguishes it from sibling tools that create runs or estimate packages. The phrase 'completed bounded v0' adds precise scope.

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 this tool is for fetching jobs after creation, with a note that only inline completed jobs are supported under the current contract. It does not explicitly say 'use this after create_geometry_export' or list when not to use it, leaving the guidance implicit.

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, so the read-only nature is known. The description adds behavioral context: it is a discovery step, returns specific metadata types, and includes first-query examples. No contradictions.

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, front-loaded with 'Free discovery'. Every phrase adds value: what it returns, when to call, what to learn. No fluff.

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 1-parameter read-only tool, the description covers purpose, usage context, and return contents. No output schema, but the described return fields suffice. Slightly more detail on output structure would push to 5.

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 100% coverage for pack_id, listing possible values. The description does not add new parameter meaning beyond mentioning 'one pack'. 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 it returns detailed metadata for one pack, with a specific verb 'Returns'. It distinguishes from sibling tools by focusing on a single pack's metadata, while siblings like get_catalog likely list all packs. However, it does not explicitly differentiate from siblings, so score 4.

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 'Call this before querying a new pack' and explains what can be learned (time shape, coverage limits, first query). It provides clear context for when to use, but no when-not or alternative siblings are mentioned.

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 description extensively discloses behavioral traits beyond the readOnlyHint annotation, including 'what it refuses', 'effective access limits', 'provenance fields', and the 'natural-language-to-strict-JSON interaction contract'. This provides substantial insight into the tool's behavior and outputs.

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 compact—two sentences—with the primary purpose front-loaded. The list of returned content is informative and each clause earns its place without redundancy.

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 single parameter, no output schema, and readOnly annotation, the description provides a thorough overview of what the tool does, what it returns, and the recommended workflow, making it self-sufficient for an unfamiliar caller.

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 fully describes 'tool_name' as 'Exact tool name from tools/list', and the description reinforces this by saying 'Use tools/list to discover names'. With 100% schema coverage, the description adds minimal new semantic value for the parameter, so the baseline score of 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 identifies the tool as a help/metadata provider for a single tool, listing specific returned content categories (when to use, refusals, example, access limits, outputs, provenance, next calls, contract). It contrasts with the sibling geometry tools by being a meta-guidance resource.

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 explicit usage context: 'Use tools/list to discover names, then call this before an unfamiliar tool.' This establishes a clear workflow and when to invoke it. It does not explicitly mention exclusions or alternatives, but the purpose is unambiguous.

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, but the description adds valuable behavioral nuance beyond that: parentage is 'strict' and 'same-release', references are 'external or side-chain', and it reveals the tool never invents parent edges across mixed releases. The 'No payment required' note adds cost transparency absent from 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?

Six concise sentences, front-loaded with purpose, each sentence earning its place—usage, options, alternatives, and a cost note. No filler or repetition of schema content.

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?

Despite 11 parameters and no output schema, the description covers what the tool returns, how to invoke it, when to use it, and which alternatives to choose. The parameter schema handles field-level detail, and the description supplies the broader context that would otherwise be 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 coverage is 100%, so the baseline is 3. The description mentions include_hierarchy and include_references but only in the same terms as the schema; it adds minimal extra meaning beyond what the parameter descriptions already provide. No parameters are left unexplained, but the description does not elevate the parameter understanding further.

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 this as a drill-down tool for loc_ids and enumerates the exact data it retrieves (metadata, parentage, shape status, lifecycle fields, child counts). It distinguishes from siblings by explicitly directing polygon lookups to get_geometry and overlap/successor analysis to compare_geographies.

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 after resolve_point for chain details, and explicitly states alternatives for other use cases. Also clarifies how to invoke (single loc_id or stack loc_ids together), which is actionable prescriptive 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=true, and description adds crucial constraints: strict hierarchy, no bridging release seams, no natural-language decoding. This goes beyond safe-read tagging to define traversal semantics.

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?

Four sentences, front-loaded with a clear one-line summary, and every sentence earns its place: purpose, disambiguation, use case, and exclusion. No fluff.

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 moderately complex tool with 8 params and no output schema, the description covers traversal logic, exclusions, and a concrete use case. However, it does not specify what a successful response contains (e.g., loc_id rows vs. counts), which the schema hints at but doesn't fully clarify. Slightly short of complete.

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 88% and describes most parameters (parent_loc_id, admin_level, bbox, limit, offset, count_only). The description only reinforces core params but doesn't add syntax or format details beyond schema, so 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?

States a specific verb+resource: 'Strict hierarchy traversal' of loc_ids, returning descendants from a 'coherent parent chain.' Excludes the alternative 'mixed-vintage latest-per-depth point resolver,' clearly distinguishing from 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?

Explicitly states when to use ('before shape exports such as every county in a selected parent scope') and when not to ('must not bridge release seams'), also naming the alternative resolver.

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