DaedalMap Geocoding and Reverse Geocoding (loc_id)

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

Beyond the readOnlyHint annotation, description adds behavioral details: 'No payment required', 'Fast shape-only', and the limitation that it does not resolve points or explain identity relationships. These are useful for cost and expectation setting, with no contradiction to 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 with front-loaded purpose ('Fast shape-only preflight'), precise constraints, and no filler. Each clause adds 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?

For a simple read-only preflight tool, the description covers what it reports (geometry availability and vintage), its limitations, and its intended place in the workflow. Without an output schema, the description adequately explains return semantics.

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?

Input schema already describes all four parameters with 100% coverage, and description echoes the single loc_id vs bounded loc_id list distinction. It adds minimal extra meaning beyond the 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?

Description clearly states a specific verb+resource: 'Fast shape-only preflight for one loc_id or a bounded loc_id list. Reports whether each exact identity has reusable geometry and its geometry vintage.' It differentiates from siblings by explicitly noting it does not resolve points and positioning itself before get_geometry or 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?

Direct guidance: 'Use before get_geometry or an export' names the primary alternative and timing. Also excludes point resolution and identity explanation, serving as when-not guidance. This gives clear usage context.

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?

The description adds behavioral context beyond the readOnlyHint annotation, including that it is a 'free geography utility,' handles 'bounded list' inputs, and resolves through a loc_id intermediate. It does not describe output format or potential errors, but the annotation already covers the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at three sentences, with the core verb and mechanism in the first sentence, usage examples in the second, and a cost/access note in the third. Every sentence contributes meaning 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 rich schema (100% coverage) and readOnlyHint annotation, the description provides adequate context through use cases and the conversion mechanism. However, it does not explicitly state return values or output structure, relying on schema hints like 'ranked output' in the limit description.

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's mention of 'one reference, or a bounded list' and the workflow examples add some context but do not provide new details beyond the schema's parameter descriptions.

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 'converts one reference, or a bounded list of references, from one geographic reference system into another' via DaedalMap loc_id. It distinguishes from siblings by framing itself as a direct conversion utility with concrete workflow examples, avoiding ambiguity with batch-job or lookup tools.

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 usage examples ('ZIP/ZCTA to NWS fire zones, NWS zone to counties') and positions the tool as a general 'catalog-backed reference bridge.' It does not explicitly mention when not to use it or name sibling alternatives, but the context is clear enough to infer appropriate scenarios.

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 bare readOnlyHint=false annotation by disclosing synchronous execution, row limits (7,500 hosted default), response time expectations (10-20 seconds), local-runtime behavior, and identifier deduplication efficiency. These are important behavioral traits that an agent needs to predict the tool's runtime characteristics. It also aligns with the annotation (creates=true, readOnly=false) without contradiction.

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 dense and purposeful. It front-loads the core purpose, then covers output types, performance/limits, and a deduplication feature. There is no filler or repetition; every sentence adds unique information. The structure is easy to scan and digest.

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 (13 parameters, nested objects, no output schema), the description is insufficiently complete. It does not explain what the synchronous job returns (e.g., job ID, in-memory result), how to handle failures, or the meaning of key configuration groups like geography_binding. The description covers scale and performance but omits essential operational details that an agent would need to correctly invoke and use the 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 only 31%, so the description carries significant responsibility for explaining parameters. It does mention output formats and preserved fields, which loosely maps to output_format and data, but it does not clarify crucial parameters like from_system vs geography_binding, to_system, limit, min_share, or target_admin_level. The description adds high-level job context but not enough field-level semantics to compensate for the sparse schema descriptions.

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+resource: 'Creates a synchronous v0 user-data conversion job.' It clearly identifies the tool's core function and distinct output formats (JSON rows, CSV, JSON Lines, Parquet). This distinguishes it from sibling tools like estimate_conversion_job (estimation) and convert_reference (reference data), which are different operations.

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 useful context about execution environments (hosted service vs local-runtime loopback) and performance budgets, implying when the tool can be used effectively. However, it does not explicitly state when to prefer this over alternatives like estimate_conversion_job or convert_reference, nor does it mention prerequisites or exclusion conditions. The usage guidance is implied rather than 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?

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?

The annotation readOnlyHint=true already indicates a safe read operation. The description adds value by revealing it is a 'dry-run' that does not execute, is free, and provides a preview of charge units and other metrics. This goes beyond the annotation without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every phrase contributes meaning: 'Free dry-run quote' establishes cost and non-execution, and the metric list tells the user what to expect. Excellent efficiency.

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 complexity (13 parameters, nested objects, no output schema), the description is minimally viable. It lists output metrics but omits input requirements such as needing either from_system or geography_binding, and how items vs row_count relate. This is a clear gap for a tool with 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?

The description provides no parameter-specific details. Schema description coverage is 62%, leaving several parameters without descriptions (iso3, limit, min_share, bridge_vintage, target_admin_level). The description does not compensate, nor does it clarify ambiguous choices like from_system vs geography_binding or items vs row_count.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb 'estimate' and resource 'conversion job,' framed as a 'Free dry-run quote.' It explicitly enumerates what is estimated (rows, sample resolvability, output bytes, errors, charge units), distinguishing it from the sibling tool create_conversion_job which would execute the job.

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 says 'before execution,' implying this tool is a pre-flight step for create_conversion_job. It also specifies the context ('uploaded or pasted user data conversion'). However, it does not explicitly name alternative tools or state when NOT to use it, so it falls slightly 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 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds meaningful behavioral context by detailing what is returned (metadata, vintage, centroid, bounding box, optional polygon) and that no payment is required. It does not contradict annotations and adds value beyond the structured 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 in the first sentence and all subsequent sentences earning their place by adding return details, usage caveats, and the sibling alternative. It is dense but not bloated, fitting for a tool with several behavioral nuances.

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 listing return contents (metadata, vintage, centroid, bounding box, optional GeoJSON polygon) and clarifying the tool's limits. It covers purpose, alternatives, and parameter trade-offs, though it does not describe error cases or batch response shape; this is a minor gap for a straightforward read-only 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 each parameter has a solid description, so the baseline is 3. The tool description enriches parameter meaning by clarifying that loc_ids can come from any resolve_point chain and by advising when to request the polygon (only for exact rendering/clipping), which helps the agent choose include_polygon appropriately.

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 'Shape retrieval for exact loc_ids,' which clearly states the tool's verb and resource. It distinguishes from siblings by explicitly noting that it does not explain hierarchy/crosswalks and directs users to loc_id_info, making its scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: 'Prefer bbox/centroid unless exact rendering or clipping requires the polygon.' It also states when not to use this tool by pointing to loc_id_info for hierarchy/crosswalk details, which is clear alternative-selection 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 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?

Annotations indicate readOnlyHint=true, consistent with 'Free discovery'. The description adds specific behavioral details about what the tool returns (metadata, freshness, guidance), enhancing transparency beyond 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, each carrying value: first states outputs, second states usage context. No wasted words, front-loaded with key information.

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 low complexity, one parameter, and no output schema, the description adequately covers purpose, usage, and expected outputs. Slightly lacking details on output structure, but acceptable without 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?

With 100% schema coverage, the parameter pack_id is well-defined in the schema with examples. The description adds context by tying the parameter to the pack identifier but does not significantly extend the schema's 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 clearly states the tool returns metadata, coverage, freshness, guidance, and examples for one pack. It uses specific verb 'returns' and resource 'one pack', differentiating from sibling tools by focusing on pack metadata.

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 advises calling this tool before querying a new pack to check time shape, coverage limits, and first query. It lacks explicit when-not-to-use or alternative tools, but the guidance is clear and actionable.

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 context that this is free, family-level, and includes 'when the client must ask a clarification.' This goes beyond simple read-only disclosure, though it doesn't detail return format or side effects.

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 the tool's purpose, and a compact enumeration of topics. Every sentence adds value without unnecessary padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an orientation tool with no output schema and a single optional parameter, the description adequately conveys the family's scope, key concepts, and the relationship to sibling tools. It is complete for its intended role.

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% for the single optional 'question' parameter, and the schema provides a description. The tool description does not add parameter-specific meaning, which is acceptable given the 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 states a specific verb ('Explains') and resource ('the DaedalMap geography/geometry MCP'), and explicitly lists the topics covered (loc_id spine, workflows, etc.). It clearly distinguishes this family-level orientation from get_tool_help, which is for one exact tool.

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 explicitly frames this as a family-level orientation and provides a direct alternative: 'Use get_tool_help for one exact tool after reading this overview.' This gives clear when-to-use and when-to-use-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?

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?

The annotation readOnlyHint=true already declares this as a non-mutating, safe operation. The description adds the 'Free geography utility' framing which reinforces the non-commercial nature but doesn't contradict annotations. It doesn't disclose pagination, result ordering, or whether the list is static vs dynamic per catalog state, but for a read-only listing tool the annotation plus description provides adequate transparency.

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?

Well-structured with the core purpose front-loaded in the first sentence, followed by specific enumerated return content and usage guidance. The final sentence about payment could be considered somewhat redundant with the 'Free' opening but is short. Slightly verbose in the middle section enumerating content types, though this detail is genuinely useful for an agent deciding if this tool returns what it needs.

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?

This is a simple list/enumeration tool with zero required parameters and a clear purpose. The description thoroughly specifies what kind of data is returned (systems, families, artifacts, counts, vintages, licenses) and the use case. No output schema exists, but given the enumerative nature described, the description is complete enough for an agent to know what to expect. Could mention result count or pagination limits but this is minor for a lightweight utility.

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 has only one optional parameter (request_id) with 100% schema description coverage, described as 'Optional caller-supplied request id for tracing.' The description adds no additional parameter semantics, but with only one optional tracing parameter that the schema already explains fully, there is minimal room for value-add beyond the schema. Baseline for high coverage applies.

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?

Clear specific verb+resource: 'Lists the currently exchangeable geographic reference systems in DaedalMap.' The description states exactly what it enumerates (geometry families, bridge artifacts, row counts, vintages, target levels, source licenses) and even names example systems (ZIP/ZCTA, NWS zones, tribal areas, marine ids, NUTS). This distinguishes it from sibling tools like get_catalog, lookup tools, and conversion tools that operate on individual records rather than enumerating available systems.

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 call: 'Call this first when you need to know whether ZIP/ZCTA, NWS zones, tribal areas, marine ids, NUTS-style regional ids, or other systems can be exchanged through loc_id.' This frames the tool as a prerequisite check before using loc_id-based exchange, giving clear decision context. It also includes a negative-economic note ('No payment required') signaling there is no cost barrier to invoking it early.

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 annotation, the description adds valuable context beyond that: it clarifies that parentage is strictly stored and never invents edges across mixed releases, that include_hierarchy returns the same-release ancestor chain, and that include_references returns external/side-chain crosswalks. These behaviors are not inferable from the annotation alone and help the agent understand edge cases.

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, then provides usage options and alternatives in a logical flow. Each sentence earns its place: the first sentence defines the tool, the second explains input modes, the third specifies optional toggles, and the fourth gives sibling differentiation plus a practical note. No redundant or filler 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?

Given the complexity of 11 parameters and two mutually exclusive input modes, the description provides a sufficient overview of what data is returned (metadata, parentage, shape status, vintage/lifecycle, child counts) and clarifies key flags. Since there is no output schema, this description covers the essential behavioral context needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds semantics beyond the schema by explaining that loc_ids can be passed together as a stack, clarifying the anyOf relationship, and describing the intent of include_hierarchy and include_references. It does not detail every parameter, but the schema already handles those; the description's extra context earns a 4.

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 drill-down for loc_ids returned by resolve_point and other geography calls, listing the types of metadata and relationships returned. It explicitly distinguishes itself from siblings by pointing to get_geometry and compare_geographies for different use cases, making its purpose unique and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: it states this is the place for detailed chain explanation, notes that resolve_point intentionally stays compact, and gives clear alternatives for polygons (get_geometry) and overlap/successor analysis (compare_geographies). It also mentions the optional include_hierarchy and include_references flags to tailor the query.

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 annotation already covers safety. The description adds valuable behavioral context: 'Free geography discovery' and 'No payment required' disclose cost implications, and 'agent-friendly form' hints at output formatting. This goes beyond the annotation without contradicting it.

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 focused sentences with no waste. It opens with a useful headline ('Free geography discovery'), then states purpose, gives view guidance, and closes with payment note. Every sentence earns its place and the text is well-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 is a read-only catalog reader with no output schema, the description adequately explains what the agent can accomplish and how to approach it. It could be more explicit about return formatting, but the tool's simplicity and the provided guidance cover the key aspects. Sibling differentiation via 'loc_id tools' adds 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 coverage is 100%, so parameter basics are documented. The description adds extra meaning for the 'view' parameter by advising to start with 'summary' and use 'full' only when necessary, which is not present in the schema. This enhances the agent's ability to choose values effectively.

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+resource: 'Reads the DaedalMap geometry catalog' and enumerates the content (collections, families, banks, crosswalk products, named reference objects). It clearly differentiates from sibling tools by framing itself as a discovery step 'before choosing loc_id tools', making its role distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use view="summary" first; use view="full" only when you need the whole catalog.' It also contextualizes when to invoke the tool ('before choosing loc_id tools'). It does not explicitly name alternative tools or exclusions, but the guidance is sufficient for appropriate 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?

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?

The description adds substantial context beyond the readOnlyHint annotation, including the intentional smallness of each chain row, exclusions (no polygons, hierarchy analysis, etc.), and operational constraints such as the 25-point preview threshold, required scope for batches, and payment/throughput differences for anonymous vs. verified callers. It does not contradict the readOnlyHint.

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 longer than the ideal two-sentence example but every sentence carries information. It is front-loaded with the core purpose and quickly moves to exclusions and usage rules. Some redundancy exists ('Compact reverse geocoding' vs. 'Converts...'), but overall each 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?

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the output format ('loc_id, name, admin level, and vintage when available'), specifies limits and requirements, and points to sibling tools for related needs. The absence of an output schema is compensated by the explicit description of the returned chain structure.

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 meaningful usage semantics for parameters by explaining when country_scope and target_admin_level are optional vs. required, and when to use bulk_preset instead. It doesn't add syntax-level detail, but the schema already covers that.

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 main function: 'Converts one WGS84 point, or a bounded point list, into the latest-available administrative loc_id chain.' It also explicitly distinguishes from siblings by listing what it does NOT return (polygons, hierarchy analysis, etc.) and directing users to alternative tools for those features.

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 usage guidance: 'Pass the returned stack loc_ids to loc_id_info for details; use get_geometry for shapes and compare_geographies for relationships.' It also clarifies when to use scope parameters: small exploratory calls may omit scope, while batches above 25 points must declare exactly one country_scope and target_admin_level, with bulk_preset as an alternative for cross-country batches.

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 annotation readOnlyHint=true already signals safe read operation; the description adds useful context by stating 'No payment required' and detailing return contents ('ranked loc_id matches with bridge vintage, overlap weights, and provenance where applicable'). This goes beyond the annotation to inform the agent about response characteristics, though it doesn't disclose potential limitations like rate limits or error conditions.

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 focused sentences: it states the utility, gives examples, and describes the output. Every sentence carries meaningful information with no redundancy or fluff, making it highly concise and well-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 complexity (13 params, no output schema), the description provides a reasonable overview of input modes ('one value' or 'bounded list') and output characteristics (ranked matches with bridge vintage, weights, provenance). It doesn't fully specify the response structure, but the examples and output summary offer sufficient orientation for an AI agent.

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 semantic value beyond schema: it provides examples of from_system and value pairs and summarizes the 'bounded list' concept, but these are largely redundant with the detailed schema descriptions. No new parameter guidance is provided.

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 ('Converts') and resource ('external or adjacent geographic reference system into the DaedalMap loc_id universe'). It includes concrete examples of input systems (zip, nws_fire, admin_boundary) and output details, distinguishing it from sibling tools like resolve_point and list_reference_systems.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage as a general utility ('Free geography utility') and provides examples, but it does not explicitly state when to use this tool versus alternatives like convert_reference. There is no mention of when not to use it or clear guidance on tool selection.

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