DaedalMap Geography Tools (loc_id)

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

The readOnlyHint annotation already establishes safety, and the description adds meaningful behavioral nuance: historical geometry is the primary result, a current successor is only an explicit follow-up, and the call is a fast shape-only preflight. It also notes no payment is required, which is useful 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?

Five short sentences, each earning its place: what it does, what it reports, primary-result behavior, exclusions, and when to use it. The most decision-relevant information is front-loaded.

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 read-only preflight with two documented parameters and no output schema, the description is complete. It tells the agent what is returned, what is not returned, when to call it, and what constraints apply to the input.

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 clearly. The tool description adds the 'bounded' qualifier and reinforces the single-vs-list choice, which helps an agent select the correct argument shape without opening 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?

States a specific action ('shape-only preflight'), a specific resource ('geometry availability'), and the exact unit of work ('one loc_id or a bounded loc_id list'). It also distinguishes itself from sibling tools by explicitly saying it does not resolve points or explain other identity relationships.

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?

Gives clear usage context: 'Use before get_geometry or an export.' It also signals when not to use it by excluding point resolution and identity-relationship explanation. It does not explicitly name the alternative tools for those excluded behaviors, so it stops just short of fully explicit routing.

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 adds meaningful behavioral context beyond that: it mentions conditional execution ('when approved geometry exists'), the nature of results (temporal validity, N-way successor context, topology, etc.), and 'No payment required' as an operational note. It does not contradict annotations and provides useful transparency about output 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?

The description is five sentences, each earning its place: purpose, return content, usage context, caveat, alternative, and payment status. It is front-loaded with the primary purpose and uses clear, direct language 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 tool's complexity (9 params, anyOf input patterns, no output schema), the description adequately summarizes the return categories and usage nuances. It does not describe batch behavior via 'items', but the schema covers that. Slight room remains to mention asynchronous or batch limitations, but overall it is complete enough for selection and 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 input schema has 100% parameter description coverage, so the schema already documents all parameters. The tool description itself does not detail individual parameters but instead gives high-level context about the tool's purpose. This meets the baseline for a schema-heavy tool, though it adds no extra parameter-level meaning.

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 'Detailed relationship tool for two geographic identities' which clearly states the verb (compare/relate) and resource (two geographic identities). It further distinguishes from siblings by explicitly positioning it 'after a compact point lookup when the caller asks whether two tiers/releases really contain or overlap one another' and directs users to resolve_reference for name resolution.

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 when-to-use guidance ('Use this after a compact point lookup...'), an alternative ('Use resolve_reference first for names or outside identifiers'), and a key caveat ('A point-chain seam is not proof of strict parentage'). This fully covers usage context and distinguishes when to select 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 declare readOnlyHint=true, and the description adds behavioral context beyond that: it is 'Free geography utility' with 'No payment required,' and it explains the internal resolution path (X -> loc_id -> Y). This gives the agent useful insight into how the conversion works without contradicting the read-only hint.

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 and front-loaded with the core purpose. The only redundancy is 'No payment required,' which repeats the earlier 'Free geography utility' assertion, but overall every other sentence earns its place and the examples are scannable.

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 (11 parameters, no output schema, many siblings), the description covers high-level purpose and use cases but leaves gaps around output/ranking behavior, the role of target_admin_level or relationship_vintage, and how results are ordered or scored. The schema documents parameters well, but the description does not fully bridge the absence of an output schema.

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 value by providing concrete examples of valid from_system/to_system values (ZIP, ZCTA, NWS fire zones, counties) and by explaining the single vs. bounded-list mode ('one reference, or a bounded list of references'), which clarifies the two top-level invocation styles.

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 explicitly states the verb (converts), the resource (geographic reference), and the mechanism (resolving through DaedalMap loc_id: X -> loc_id -> Y). It also lists concrete use cases (ZIP/ZCTA to NWS fire zones, NWS zone to counties) that clearly distinguish it from sibling tools like identify_reference_system or resolve_reference.

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 context for when to use the tool: 'Use this for workflows like ZIP/ZCTA to NWS fire zones, NWS zone to counties, county to overlapping ZCTAs, or any future catalog-backed crosswalk.' However, it does not explicitly state when not to use it or name alternative sibling tools, so it misses the highest bar for exclusions/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?

The description adds substantial behavioral detail beyond the readOnlyHint=false annotation: synchronous execution, a hosted 7,500-row default, a 10-20 second response budget, local-loopback behavior with no service cap, and identifier deduplication. This gives the agent useful expectations about limits, performance, and execution semantics. No contradiction with annotations exists.

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 the core action, resource, and output formats front-loaded. The second and third sentences add capacity, performance, and behavioral context without fluff. 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 complex tool with 13 parameters, low schema coverage, and no output schema, the description omits critical information: no response/return structure, no explanation of the items array's role, and no mention of the from_system versus geography_binding choice. An agent would still need external schemas or help to invoke this correctly on non-trivial inputs.

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 31%, and the description does not explain the core conversion parameters such as from_system, geography_binding, to_system, iso3, limit, min_share, target_admin_level, or relationship_vintage. It adds useful context around output_format and overall item counts, but most of the 13 parameters remain underspecified. The description only partially compensates for the schema's low 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 states a specific action and object: 'Creates a synchronous v0 user-data conversion job' and immediately specifies output formats. This goes beyond the title and helps distinguish it from estimate and geometry siblings, though it never explicitly names an alternative. It is clear but sibling differentiation is implicit rather than stated.

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 explicit guidance on when to use this tool versus estimate_conversion_job, convert_reference, or resolve_reference. The 'synchronous' qualifier hints at immediate conversion use, but no prerequisites, exclusions, or alternative-selection conditions are given. The agent is left to infer routing.

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?

Beyond readOnlyHint=false, description discloses synchronous behavior, response budget (10-20s), item cap (250) configurable by deployment, and no cap for local loopback. Lacks explicit side-effect or auth details, but annotations already signal mutation; these operational details add value.

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 dense sentences, each adding distinct operational context; no filler, front-loaded with primary purpose and followed by constraints and guidance.

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 8 parameters, a nested scope, and no output schema, the description is insufficiently complete. It omits what the tool returns (e.g., download URL vs inline data), how scope fields combine, and the meaning of output_name/include_polygon. The access-lane guidance is helpful but does not cover the complexity.

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 38%, and description does not compensate. It mentions loc_ids/scope/format but leaves output_name, include_polygon, quote_id usage/unexplained, and nested scope properties unelaborated.

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 and resource: 'Creates a synchronous v0 geometry export' from loc_ids or scope, with explicit formats (GeoJSON, gzipped, zipped). Distinguishes from siblings like estimate_geometry_package (estimation) and get_geometry (retrieval) by emphasizing creation and format.

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 conditional usage context: mentions hosted service default limits vs local-runtime loopback no cap, and explicitly directs user to estimate_geometry_package or get_tool_help for effective access lane, which serves as an alternative/exclusion instruction.

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 reinforces this by stating 'dry-run' and 'before execution', indicating no side effects. It adds that the quote is 'free' and estimates charge units, which is useful context. However, it does not discuss authentication, rate limits, or what happens on error, but given the read-only nature, the description is adequate and consistent.

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 'Free dry-run quote', and conveys the core value without extraneous words. It is concise and well-structured, though it could have added one clarifying sentence about input modes without becoming verbose.

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 13 parameters, nested anyOf schemas, and no output schema, the description is insufficient. It does not explain how to provide input (items vs row_count), the role of geography_binding, or how output_format affects the estimate. An agent would need to dig into the schema to understand request formation, which is a significant gap for this complexity.

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 62%, and some parameters already have descriptions (e.g., data reserved columns, to_system, output_format). The description mentions 'uploaded or pasted user data' which hints at the items or row_count modes but does not explain the anyOf structure or how to choose between them. It also does not clarify geography_binding semantics beyond what is in the schema. It provides partial value but does not fully compensate for unpresented 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?

The description clearly states it is a 'free dry-run quote' for 'user data conversion' and lists specific estimates (rows, sample resolvability, output bytes, errors, charge units). This distinguishes it from sibling tools like create_conversion_job, which actually performs conversions, and estimate_geometry_package, which focuses on geometry packages.

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 it is for pre-execution estimation ('before execution') and is a dry-run, but it does not explicitly state when to use this instead of alternatives like create_conversion_job or how it differs from other estimate tools. No exclusions or alternative routing is mentioned; the intent is inferred from 'dry-run quote'.

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 reinforces this with 'Dry-run' and 'estimates an export artifact'. It adds valuable context by disclosing exactly what the estimate covers (loc_id count, shape/vintage availability, bytes, delivery mode, citation requirements, charge units) and explicitly excludes canonical release bundles. No contradictions or hidden side effects are indicated.

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 purpose ('Dry-run estimate for a selected geometry export') and followed by a clarifying exclusion. Every word adds value—no filler or redundancy. It is highly concise and effectively 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?

For a read-only tool with a rich schema and no output schema, the description adequately covers the purpose, output contents, and scope exclusions. It does not explicitly explain the input selection methods (e.g., loc_id vs. scope) but the schema covers that. Given the tool's moderate complexity and high schema coverage, the description is complete enough, though it could benefit from a direct pointer to sibling tools like create_geometry_export for contextual flow.

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 (86%), so the parameters are mostly self-explanatory from the schema. The description does not add additional parameter-level semantics beyond what the schema provides; it focuses on the output of the estimate rather than input parameter details. This meets the baseline for high schema 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 function: 'Dry-run estimate for a selected geometry export' and specifies the exact outputs (loc_id count, shape/vintage availability, bytes, delivery mode, citation requirements, charge units). It also differentiates from a 'canonical DaedalMap geometry release bundle', distinguishing this estimation tool from other geometry-related tools in the sibling list.

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 effectively implies when to use this tool: when a dry-run estimate is needed before a geometry export. It provides context by naming specific estimate dimensions and clarifying it is not a canonical release bundle, but it does not explicitly name alternative tools or state 'use this instead of X'. The guidance is clear though not fully 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 indicate readOnlyHint=true. The description adds context about the data (live, agent-ready) but does not disclose any additional behavioral traits like caching, rate limits, or pagination.

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 extremely concise: two sentences (13 words) with no wasted text. It is front-loaded with 'Free discovery' and immediately defines the output.

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 has no parameters and no output schema, the description is mostly complete. It could mention if the list is ordered or if there are any limitations, but overall it suffices.

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, and the schema coverage is 100%. According to guidelines, baseline is 4. No additional parameter information 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?

The description clearly states the tool returns a list of live agent-ready data packs available on DaedalMap, using a specific verb and resource. It distinguishes from siblings like get_pack, which likely retrieves a single pack.

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 phrase 'Free discovery' implies when to use this tool (for initial exploration), but it does not explicitly compare with alternatives or state when not to use it.

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 provide readOnlyHint:true, and the description adds significant behavioral detail beyond that: historical geometry is returned first, an evidenced successor is never substituted or fetched automatically, and no payment is required. This discloses behaviors an agent could not infer from annotations alone.

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 purpose and remains efficient. Every sentence adds value: scope, return contents, historical behavior, sibling routing, polygon guidance, and payment status. No word is wasted.

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 usefully lists the returned components and key behavior. It does not describe response envelope, error cases, or whether loc_id and loc_ids can be combined, but for a read-only geometry retrieval tool this is a minor gap given the schema already documents parameters.

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 extra meaning by clarifying that loc_ids can come from any level of a resolve_point chain and by advising when to request the polygon versus bbox/centroid. This goes beyond what the schema properties state.

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: 'Shape retrieval for exact loc_ids,' and states exactly what is returned (metadata, vintage, centroid, bounding box, optional GeoJSON polygon). It also differentiates from siblings by noting that hierarchy and crosswalk details belong to loc_id_info.

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 routing guidance: use loc_id_info for hierarchy/crosswalks, and prefer bbox/centroid unless exact rendering or clipping requires the polygon. This provides clear when-to-use and when-not-to-use context relative to 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 readOnlyHint=true, and the description reinforces this with 'Retrieves'. It adds context about the job state (completed) and explicitly disclaims future capabilities (durable queued jobs, downloadable links). 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?

Two sentences: the first fronts the core purpose and the second adds a relevant limitation. No filler, every word 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 simple retrieval tool with 2 parameters, the description covers the primary use, input source, and contract limitations. Although there is no output schema and the return format is not described, this is not critical for a by-ID lookup, and the input schema is fully self-explanatory.

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%, with both job_id and request_id documented directly in the schema. The description adds only that job_id is returned by create_geometry_export or create_conversion_job, which slightly enriches the schema but does not add significant new meaning given the schema already explains the 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 the tool 'Retrieves a completed bounded v0 geometry export or conversion job by job_id' – a specific verb, resource, and identifier. It distinguishes itself from sibling creation tools like create_geometry_export and create_conversion_job by focusing on 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?

It explains that the current contract only supports completed inline jobs, and that durable queued jobs and downloadable artifact links are future capabilities. This implicitly tells users when not to expect those features, and the job_id reference ties it to the creation workflow. It doesn't explicitly name alternatives, but the boundary is clear.

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 readOnlyHint annotation is set, and the description's 'Free discovery' framing aligns with a non-destructive read. The description adds value beyond the annotation by disclosing the nature of what is fetched (time shape, coverage limits, canonical tool guidance, paste-ready examples), which is useful behavioral context for a metadata tool.

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 focused sentences with the core purpose front-loaded before the usage guidance. No wasted words, though the opening 'Free discovery.' is a stylistic flourish that adds little informational value.

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 one required parameter, full schema coverage, a readOnlyHint annotation, and no output schema, the description adequately conveys the return contents (metadata, coverage, freshness, guidance, examples) so an agent knows what to expect. Nothing critical is missing for a single-identifier read tool.

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% and the schema already documents pack_id as 'Pack identifier from get_catalog.' The description adds no parameter-specific detail, but at high coverage the baseline of 3 applies; the schema carries the semantic load and does so adequately.

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 verb+resource: it returns detailed metadata, coverage, freshness, canonical tool guidance, and first-query examples for one pack. The phrase 'one pack' distinguishes it from the sibling get_catalog, which enumerates packs. It opens with a vague marketing phrase ('Free discovery'), but the substantive purpose 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?

Explicitly instructs when to call: 'Call this before querying a new pack so you can see time shape, coverage limits, and the paste-ready first query.' This gives a clear temporal trigger. However, it does not name the specific alternative (get_catalog) for discovering pack IDs or state when not to use it, leaving some routing to inference.

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?

Beyond the readOnlyHint annotation, the description discloses the types of information returned (e.g., refusals, access limits, provenance fields, interaction contract), adding useful behavioral context 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?

Two sentences: the first presents the core purpose with a detailed list of outputs, the second gives the precise usage sequence. No redundant wording.

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 fully explains what to expect from the tool—its purpose, outputs, how to discover the tool name, and when to invoke it—making it self-sufficient despite the lack of an output schema.

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 fully covers the single 'tool_name' parameter, describing it as the exact name from tools/list. The description reinforces this by referencing tools/list but does not add new semantic details about the parameter format.

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 help tool that returns guidance for a single tool, enumerating the specific output categories. It distinguishes itself from sibling domain tools like check_geometry and convert_reference.

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 instructs to use tools/list to discover names and then call this before an unfamiliar tool, providing a clear workflow and context of use.

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 adds helpful behavioral context: this is a free guide, it should be invoked first, and it explains automatic deeper administrative tiers where available. It does not describe the response format, but that is less critical for a help/guide tool. 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 well-structured and front-loaded with the key instruction to call this first. It then provides a logical flow to other tools and includes current catalog data. It is somewhat longer than strictly necessary, but the extra detail about country coverage and automatic depth behavior is relevant and 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 an onboarding/guide tool, the description covers the conceptual scope, the recommended sequence, and the current catalog breadth across countries and admin levels. It does not state what the response looks like or the exact phrasing of the optional question parameter, but given the tool's purpose and the fully documented schema, this 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 input schema already provides 100% coverage of the single optional parameter with a clear description ('Optional natural-language question about how to use the geometry tool family'). The tool description does not add additional parameter-level guidance, 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 this as a starting guide, specifies the actionable directive to call it first, and enumerates the concepts it teaches (loc_id, administrative-spine, reference-family, discovery, point-lookup, bounded-shape). It explicitly differentiates itself from sibling tools like read_geometry_catalog and get_tool_help by describing their distinct roles.

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 provides explicit workflow guidance: call this first to learn concepts, then read the live geometry catalog for country-specific guidance, and use get_tool_help for one exact tool. This directly tells the agent when to use this tool versus the alternatives, leaving no ambiguity.

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 goes well beyond the readOnlyHint annotation by detailing return behavior (ranked candidates, deterministic warnings, clarification questions, counts, recommended binding), the bounded-sample limitation, and the fact that it is free. It also explicitly states non-goals, providing thorough behavioral context.

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?

Each of the six sentences adds distinct value: purpose, input formatting instruction, use case, output contents, exclusions, and cost. There is no redundancy or filler, and the structure front-loads the core function before details.

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?

Since there is no output schema, the description carries the burden of explaining return values, and it does so thoroughly by listing ranked candidates, warnings, clarification questions, counts, and recommended geography_binding. It also covers scope and limitations, making it complete for a tool of this complexity.

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 83% schema coverage, the schema already describes parameters well. The description adds valuable LLM-specific guidance (extract identifiers, pass as strings, do not include prose, preserve leading zeros) which is not fully captured in the schema, especially for the singular identifier parameter. This pushes it above the baseline of 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 uses a specific verb ('checks') and resource ('identifiers against maintained reference indexes and geometry banks'), clearly stating the tool's purpose. It also explicitly states what it does not do ('does not convert the full dataset or return polygons'), distinguishing it from sibling tools like convert_reference and get_geometry.

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 context: 'Use it when a caller has geography keys but is unsure which system, level, or bank they belong to, or wants to verify a declaration...'. It also gives a when-not by stating it does not convert or return polygons, but does not explicitly name a sibling tool as the alternative, so it falls just 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?

Annotations only declare readOnlyHint=true, so the description adds meaningful behavioral context: it reads a canonical registry, never exposes WIP or relationship-only records on public calls, and requires no payment. These details go beyond the safety hint and help the agent anticipate response boundaries.

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, front-loaded with the core listing purpose, and each sentence carries useful guidance. Minor redundancy exists between 'Free geography utility' and 'No payment required,' but the overall structure remains efficient and readable.

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 compensates by enumerating key return fields (row counts, vintages, target levels, source license metadata) and stating what is not exposed. It also gives clear first-step guidance. It could elaborate on pagination or response shape, but for a list/discovery tool with zero required parameters, it is sufficiently 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, but the description adds practical guidance beyond the schema by saying 'Pass country_scope whenever the country is known' and clarifying that public calls never expose WIP. This gives the agent extra decision-making context for parameter use.

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 uses a specific verb ('lists') and a concrete resource ('published, callable geographic reference systems' from the 'canonical crosswalk registry'), and names the exact metadata fields returned. It also frames the tool as the discovery entry point for loc_id exchange capabilities, which separates it from sibling resolve/convert tools without needing to inspect their schemas.

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 tells the agent to 'Call this first' when learning whether identifiers can be exchanged, and instructs to 'Pass country_scope whenever the country is known.' It does not name alternative tools or state when not to use the tool, so it stops short of full exclusion 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: historical records are returned only as requested, an evidenced successor is never substituted or fetched automatically, and the caller is separately asked whether supersession is wanted. It also clarifies that hierarchy is 'strict same-release ancestor chain' and does not invent parent edges across mixed releases.

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 tool's purpose and remains compact despite covering usage, alternatives, key flags, and behavioral caveats. Every sentence earns its place, and the alternative routing is stated efficiently 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?

For an 11-parameter tool with no output schema, the description covers the essential context: what the tool returns, how loc_ids should be passed, how historical/supersession behavior works, which flags control hierarchy/references, and which sibling tools handle other cases. Combined with the 100%-covered parameter schema, an agent has enough information 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 100%, so the schema already documents all parameters. The description adds meaningful semantic nuance: loc_ids can be passed as 'the point result's stack loc_ids together,' include_hierarchy means the 'strict same-release ancestor chain,' and include_references covers 'external or side-chain crosswalks.' This goes beyond the baseline without needing to re-document every 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 names a specific resource and action: it is 'the drill-down tool for loc_ids returned by resolve_point and other geography calls' and lists exactly what it retrieves: metadata, parentage, shape status, vintage/lifecycle fields, and child counts. It also differentiates itself from siblings by saying 'This is where detailed chain explanation belongs; resolve_point intentionally stays compact.'

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 and alternative routing: use this tool for loc_id drill-downs and chain explanation, use get_geometry for exact polygons, and use compare_geographies for overlap or successor analysis. It also tells the caller to set include_hierarchy and include_references for specific needs, making the when-to-use decision clear.

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, and the description reinforces a read-only profile. It adds meaningful behavior beyond the annotation: default excludes staged/candidate work, read_wip is only for local loopback MCP, and the catalog delivers deeper administrative tiers where country releases exist. 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 core operational guidance is front-loaded in the first three sentences, which is good. However, 'Free geography discovery.' and 'No payment required.' add little for tool invocation, and the 'Current catalog:' paragraph is lengthy informational context rather than concise operational guidance.

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 covers default scope, view selection, read_wip restrictions, and geographical availability. But with no output schema, it does not describe the return shape or pagination behavior, and it leaves sibling differentiation (notably vs. get_catalog) unaddressed, so the agent must infer some aspects from tool name and schema.

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 all five parameters. The description goes a step further by advising view='capabilities' first and by explaining that read_wip=true is for local loopback MCP internal review only, which adds selection context over the raw enum and boolean 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 clearly identifies the resource and operation: 'Reads the published DaedalMap geometry catalog projection by default.' This distinguishes it from generic read operations, but it does not explicitly distinguish it from the sibling tool 'get_catalog', and the opening 'Free geography discovery' is vague marketing rather than useful purpose statement.

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 actionable internal guidance: 'Use view=\'capabilities\' first for the global baseline and enhanced countries; use focused inventory views for families, banks, crosswalk products, and named objects.' It also clarifies the default behavior and the local-loopback-only read_wip path. However, it does not explicitly contrast this tool with alternatives like get_catalog or state when not to use it.

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?

Given the readOnlyHint annotation, the description adds substantial behavioral context beyond it: strict hierarchy traversal, coherent parent chain, the restriction on bridging release seams, and the absence of natural-language decoding. These traits describe how the tool behaves, not just that it is read-only.

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, each earning its place. It opens with the core behavior, adds a contrast, gives a concrete use case, and closes with a limitation. 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?

For a moderate-complexity tool with 8 parameters and no output schema, the description covers the essential conceptual model and usage. It does not explain optional parameters like bbox/limit/count_only, but the schema descriptions handle those. The core semantics and constraints are well-covered, though a bit more detail on return shape would push it 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?

Schema coverage is high (88%), so the baseline is 3. The description adds meaning by highlighting the key inputs 'parent_loc_id' and 'target admin level,' and clarifying that no natural-language decoding is performed, which gives extra semantic nuance to the admin_level parameter beyond the schema's examples.

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 function with a specific verb and resource: 'Strict hierarchy traversal... returns descendants from that coherent parent chain.' It distinguishes itself from the sibling resolver by explicitly contrasting with the 'mixed-vintage latest-per-depth point resolver,' making its unique 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?

Usage guidance is explicit: 'Use it before shape exports such as every county in a selected parent scope.' It also provides exclusions: 'must not bridge release seams' and 'No natural-language decoding is performed,' clarifying when not to use it and differentiating from natural-language 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?

With readOnlyHint=true already covering the safety profile, the description adds substantial behavioral context: output rows are intentionally small, the tool does not return polygons or hierarchy analysis, and results reflect the latest available administrative chain. It also discloses throughput and payment behavior for anonymous vs verified callers, and explains how country catalog depth affects 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?

The description is front-loaded with the core purpose and exclusions, then moves through usage constraints, billing, and catalog depth in a logical order. It is longer than strictly necessary, especially the current-catalog country list, but every major section adds decision-relevant context for a 9-parameter tool with no output schema.

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 having no output schema, the description tells the agent exactly what each chain row contains: loc_id, name, admin level, and vintage. It covers exclusions, sibling routing, parameter requirements, billing thresholds, and geographic coverage, leaving no critical gap for an agent deciding whether and how to call this tool.

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 individual parameter definitions are already handled. The description adds value by clarifying conditional parameter behavior: 'exactly one' country_scope and target_admin_level above 25 points, the need to split multi-country input, and bulk_preset as a substitute for cross-country batches. Some billing and threshold details duplicate schema text, but the added constraints 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 opens with a precise verb and resource: 'Converts one WGS84 point, or a bounded point list, into the latest-available administrative loc_id chain.' It also differentiates itself by explicitly listing what it does not return and names the sibling tools that should be used instead, so an agent can distinguish this from get_geometry, compare_geographies, and loc_id_info.

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?

Usage rules are explicit: small exploratory calls may omit scope, batches above 25 must declare exactly one country_scope and target_admin_level, multi-country input must be split, and bulk_preset is the recommended path for cross-country admin-0/admin-1 batches. The description also tells the agent when to route to loc_id_info, get_geometry, and compare_geographies, which is strong alternative 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?

Beyond the readOnlyHint annotation, the description discloses useful behavioral traits: it is free, returns ranked matches with bridge vintage, overlap weights, and provenance, and never automatically substitutes an evidenced successor. It also clarifies that historical references are returned as requested, adding meaningful 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 compact, front-loaded with the core purpose, and uses examples effectively. The historical-behavior and no-payment statements are useful but make the description slightly denser than strictly necessary.

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 utility with no output schema, the description explains the main return fields and important behavioral caveats such as no automatic successor substitution. It is mostly complete, though it could strengthen agent decision-making by addressing how it differs from convert_reference and when batch input is preferred.

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 schema already documents all parameters well. The description adds examples for from_system/value pairs and mentions bounded lists, but it does not materially explain parameter semantics beyond what the schema provides.

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 function: converting external or adjacent geographic reference values into DaedalMap loc_id values, and it names the output as ranked matches. It is specific about the resource and outcome, but it does not explicitly distinguish itself from the sibling convert_reference tool, so it falls short of full sibling differentiation.

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 when to use this tool—when you have an external reference value and need loc_id matches—and gives concrete examples. However, it does not explicitly state when not to use it or mention alternatives such as convert_reference, identify_reference_system, or resolve_point.

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