DaedalMap Disaster and Geospatial Data

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

The readOnlyHint annotation already signals a safe read, and the description adds substantive behavioral detail beyond that: it is fast, shape-only, reports vintage, treats historical geometry as primary, treats successor geometry as an explicit follow-up, and requires no payment. This is rich, non-obvious context that helps an agent understand side effects and expectations.

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 every sentence adds distinct value: scope, output type, historical vs successor behavior, exclusions, usage timing, and payment. There is 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 read-only preflight tool with no output schema, the description covers what an agent needs to select and invoke it: what it reports, when to call it, what it intentionally does not do, and cost implications. It does not specify the exact output structure, but the semantic output is clear enough for a tool of this simplicity.

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

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

The input schema has 100% coverage for its parameters, so the schema already documents loc_id, loc_ids, batch_id, and request_id. The description adds a useful 'bounded loc_id list' constraint and clarifies 'exact identity,' but it does not meaningfully expand parameter meaning beyond the schema baseline.

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 action ('check') on a specific resource ('geometry availability for loc_id(s)') and immediately distinguishes itself from siblings: it is a shape-only preflight that does not resolve points or explain identity relationships. The title and description align, so an agent can reliably tell this from get_geometry and resolve_point.

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

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

The description explicitly says to use this before get_geometry or an export, giving concrete timing guidance. It also states exclusions ('does not resolve points or explain other identity relationships'), which prevents misuse when resolving points or tracing identity is the goal.

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 include readOnlyHint=true, and the description adds conditional behavior ('when approved geometry exists') and the caveat about point-chain seams. It does not contradict annotations and provides useful context beyond 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?

Four sentences, front-loaded with the core purpose. The inclusion of 'No payment required' is slightly extraneous but does not significantly harm clarity.

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 9 parameters and no output schema, the description covers key return values and usage context. It lacks explicit mention of batch usage via the 'items' parameter, but the schema covers that. It is otherwise quite 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 description coverage is 100%, so the schema already documents all parameters. The description adds no additional parameter-level detail; baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Detailed relationship tool for two geographic identities' and lists specific outputs (temporal validity, successor context, topology, geodesic intersection area, overlap shares). This distinguishes it from sibling tools like get_geometry or resolve_point.

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 usage context: 'Use this after a compact point lookup' and directs to 'Use resolve_reference first for names or outside identifiers.' Also gives a critical caveat: 'A point-chain seam is not proof of strict parentage.'

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context: it is a 'Free geography utility' with 'No payment required', and it handles a 'bounded list' of references, implying rate/volume limits. It also explains the internal resolution chain (loc_id). This adds value beyond the annotation, though it does not disclose error handling, pagination, or exact output format, which are not required given the annotation coverage.

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 with no wasted words. The core action is front-loaded, followed by mechanisms and examples. The final sentence about payment is a brief differentiator. It is tight, informative, 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 tool's complexity (11 parameters, batch mode) and lack of an output schema, the description is reasonably complete. It explains the purpose and typical workflows, which is enough for an agent to invoke it correctly. However, it does not specify return format or error/edge-case behavior, but the extensive schema descriptions cover parameter semantics. Given that the tool is read-only and the schema is detailed, the description 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by clarifying the single vs. batch modes ('one reference, or a bounded list of references') and giving examples of valid from/to systems within workflows. It also implies the 'limit' and 'min_share' parameters refer to ranked output, aligning with the schema. This is modest extra context that complements the thorough 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 states a specific verb ('Converts'), a clear resource ('geographic reference system'), and the scope (one reference or a bounded list). It explicitly explains the mechanism (resolving through DaedalMap loc_id: X -> loc_id -> Y) and provides concrete workflow examples (ZIP/ZCTA to NWS fire zones, NWS zone to counties, county to overlapping ZCTAs). This clearly distinguishes it from sibling tools like resolve_reference, which likely handles single-reference 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 gives explicit use cases: '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.' This tells an agent when to apply the tool. However, it does not explicitly say when not to use it or name alternative tools, relying on the workflow context to implicitly separate it from siblings. So it is clear but lacks explicit exclusions.

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 only readOnlyHint=false in annotations, the description carries most of the behavioral burden. It usefully discloses synchronous execution, a 7,500-row hosted default, a 10–20 second response budget, and identifier deduplication. However, it does not describe output shape, failure behavior, side effects, or any permissions requirements, leaving the picture incomplete.

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: three sentences with the core operation front-loaded and the scaling constraints after. There is minimal filler, though jargon like 'v0' and 'loopback' slightly reduces accessibility.

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

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

For a tool with 13 parameters, nested objects, an anyOf requirement, and no output schema, the description is far from complete. It does not explain the required items structure, the from_system versus geography_binding choice, row-level overrides, or what the synchronous job returns. An agent would still need substantial schema inference and sibling exploration to call it 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 description coverage is only 31%, so the description must compensate, but it names no parameters directly. It alludes to output formats and the row cap, and 'preserved scalar fields' hints at the data parameter, but from_system, geography_binding, to_system, target_admin_level, min_share, quote_id, and others remain unexplained. The description adds little beyond what the schema already exposes.

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 and resource: 'Creates a synchronous v0 user-data conversion job' and enumerates supported output formats, so the operation is identifiable. It is clear but does not explicitly differentiate itself from siblings like estimate_conversion_job or convert_reference; the 'user-data' and 'synchronous' qualifiers only imply a distinction.

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

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

There is no guidance about when to use this tool versus alternatives such as estimate_conversion_job or convert_reference. The hosted/local loopback contrast is behavioral scaling context, not a use-case selector. Prerequisites, sequencing, or exclusion conditions are absent.

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 provide readOnlyHint=false, leaving the description to carry the burden. It discloses synchrony, response budget, service-item caps, and environment-dependent behavior (hosted vs local loopback). This is substantial behavioral context beyond what annotations offer.

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 core action, then scaling limits and redirection. Every sentence contributes value without repetition or filler.

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

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

For a create/export tool with no output schema, it covers purpose, limits, access lane, and formats. The only notable omission is the return value or response structure, which is a minor gap given the tool's nature.

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 only 38% (3 of 8 params described). The description compensates by clarifying that loc_ids are an exact list with a default cap of 250, scope must be a single strict scope, format maps directly to the enum, and quote_id originates from estimate_geometry_package. Some optional params like include_polygon and output_name remain unexplained, but the core selection params gain meaningful context.

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 'Creates a synchronous v0 geometry export' from 'exact loc_ids or one strict scope', with explicit format options (GeoJSON, gzipped GeoJSON, zipped GeoJSON). This specific verb-resource pair distinguishes it from sibling tools like get_geometry (retrieval) and create_conversion_job (asynchronous conversion).

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 clear operational guidance: hosted service default of 250 loc_ids, 10-20 second response budget, and direct local-loopback exception. It explicitly directs users to estimate_geometry_package or get_tool_help for the effective access lane. However, it doesn't explicitly contrast with async alternatives like create_conversion_job, so not a full 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 readOnlyHint annotation already signals a safe, non-mutating operation. The description adds meaningful behavioral context by stating this is a free dry-run that estimates rows, sample resolvability, output bytes, errors, and charge units without executing the conversion. 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?

A single, dense sentence that front-loads the core value proposition ('Free dry-run quote') and then lists the estimated outputs. Every word earns its place; there is no fluff or redundant restating of the tool name.

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 estimation tool, the description covers the essential inputs (uploaded or pasted data) and outputs (rows, resolvability, bytes, errors, charge units). Given the absence of an output schema, this is helpful. The complex schema still carries most parameter-level context, but the description is complete enough for tool selection and initial 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?

With 13 parameters and only 62% schema description coverage, the description needed to compensate, but it adds little parameter-specific meaning. It references 'uploaded or pasted user data' and 'sample resolvability,' but does not clarify the anyOf input modes, geography_binding, or from_system semantics. Most parameter understanding must come from the schema.

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

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

The description uses a specific verb ('Estimates') and resource ('conversion job'), and clearly frames it as a free dry-run quote rather than actual conversion. The phrase 'before execution' distinguishes it from create_conversion_job, and the listed estimate outputs clarify what the tool produces.

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 communicates the key usage context: use this tool to get a pre-execution estimate for uploaded or pasted user data conversion. It implies this is the preview step before create_conversion_job, though it does not explicitly name alternative tools 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 establishes this as a safe read operation. The description adds meaningful context by specifying what the estimate covers and clarifying that it is not a canonical release bundle, which helps the agent understand the tool's non-destructive estimation behavior.

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, immediately states the tool's purpose, and wastes no words. It is front-loaded with the key action and outcome, then a short clarifying distinction.

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 complex schema and no output schema, the description compensates by listing the key return elements (count, availability, bytes, etc.). It does not explicitly state the requirement to provide loc_id, loc_ids, or scope, but the schema's anyOf enforces that, and the description is otherwise complete for an estimate 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 86%, so the schema already handles most parameter meaning. The description does not add significant parameter-level details beyond saying 'selected geometry export,' but the high schema coverage justifies the baseline score.

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

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

The description begins with 'Dry-run estimate for a selected geometry export,' using a specific verb and resource. It enumerates the exact output dimensions (loc_id count, shape/vintage availability, bytes, delivery mode, citation requirements, charge units) and explicitly differentiates from a canonical release bundle, making the purpose unmistakable.

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 clearly frames the tool as an estimator for export artifacts and excludes canonical bundles, implying use before or instead of actual export creation. However, it does not explicitly reference sibling tools like create_geometry_export or state 'use this before creating an export,' so the guidance is clear but 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, so the description does not need to repeat that. The description adds 'live agent-ready data packs' which provides additional behavioral context about the nature of the data, but it does not disclose any other traits (e.g., rate limits, freshness of data).

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 no wasted words. The essential information is front-loaded. 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?

Given no parameters, no output schema, and readOnlyHint annotation, the description provides enough context for an agent to understand what the tool returns. It could mention that it is a safe, read-only operation, but annotations already cover that. The description is complete for the simplicity of 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?

There are no parameters, and schema description coverage is 100%. The description does not need to explain parameters, and it adds no extraneous information. Baseline for zero parameters is 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?

Description clearly states the tool returns 'the list of live agent-ready data packs available on DaedalMap', which is a specific resource. The phrase 'Free discovery' adds some ambiguity but the core purpose is clear. It distinguishes from sibling tools like 'get_pack' by focusing on the catalog rather than individual packs.

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

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

No explicit guidance on when to use this tool versus alternatives such as 'get_pack' or other data retrieval tools. There is no mention of when not to use it or any context about prerequisites or limitations.

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; description adds 'free linked-disaster helper' and 'bounded' chain but no deeper behavioral detail like rate limits or return structure. Not contradictory.

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, no filler, front-loaded with key purpose. Every word serves a purpose.

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?

Covers purpose, usage, and supported packs adequately for a read-only tool with no output schema. Could describe output format but still complete enough for most use cases.

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 baseline 3. Description adds value by listing supported packs in the pack_id and event_id descriptions, but does not add major new semantics beyond schema.

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

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

The description clearly states the tool expands an exact disaster event ID into a bounded related-event chain, with specific verbs and resource. It distinguishes from siblings like search_disaster_links and get_disaster_links_for_event.

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

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

Explicitly states when to use (only with exact event id from supported pack). Lists supported packs, giving context. Does not explicitly exclude alternatives but implies exclusive use for exact ID expansion.

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 indicates the tool is read-only. The description adds that it resolves to 'published related-disaster links', but does not disclose other behavioral traits like error handling, pagination, or rate limits. It adds moderate value 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 only two sentences, with the key information in the second sentence. The first sentence ('Free linked-disaster helper') is slightly vague but not harmful. Overall efficient and 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?

Given the lack of an output schema, the description could explain return format or behavior for missing IDs. It does not mention optional parameters (pack_id, cross_type_only) or their defaults. The description is adequate but leaves gaps.

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 descriptions cover 100% of parameters, so the baseline is 3. The tool description does not elaborate on parameter meanings or provide examples beyond what the schema already contains, so no added value.

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 that the tool resolves one exact disaster event ID into published related-disaster links, specifying the verb 'resolves' and the resource 'event id' to 'links'. It implicitly distinguishes from sibling tools like search_disaster_links by requiring an exact ID, but does not explicitly compare.

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 to use this tool only when an exact event ID from a supported pack is available, providing clear context. It does not list alternative tools or exclusions, but the guidance is sufficient for basic 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?

Discloses paid nature with HTTP 402 behavior and pricing sensitivity, which goes beyond the readOnlyHint annotation, adding crucial 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?

Concise four-sentence paragraph with front-loaded purpose and no fluff, though it could benefit from structural separation of usage and payment 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?

Provides adequate context for a moderately complex tool with 6 params and no output schema, covering payment flow and lane distinction, but lacks hints about response 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 description adds minimal parameter detail beyond existing schema. It mentions query breadth cost implications but does not explain parameter formats or relationships.

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 it queries earthquake events from the enriched DaedalMap history lane, distinguishing it from the preliminary upstream wrapper and sibling tools like get_live_earthquake_events.

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 advises to use this first for earthquake questions and describes the 402 payment flow and filter optimization, though it does not explicitly state when not to use it or name 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, so the description adds value by explaining query mechanics (region_ids, time granularity) and output granularity (daily/weekly/monthly). There is no contradiction, and the description enriches 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?

Two sentences efficiently deliver purpose and key usage details. 'Free tool' is front-loaded, and the second sentence packs essential information without superfluous text.

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 (6 params, nested objects, no output schema) and annotations, the description adequately covers the core query behavior and granularity options. It does not explain sort, limit, or output, but the schema covers those, making the description 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%, but the description adds meaning by specifying that 'filters.region_ids plus filters.time.granularity' determine daily/weekly/monthly returns. This goes beyond the schema's generic description, providing actionable parameter semantics.

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 'Queries the currency pack using filters.region_ids plus filters.time.granularity to return daily, weekly, or monthly FX data.' It specifies the resource (currency pack), action (queries), key parameters, and output granularity, distinguishing it from sibling tools like 'query_dataset' or 'get_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 description opens with 'Free tool,' hinting at no cost, but does not explicitly state when to use this tool versus alternatives like 'query_dataset' or 'get_catalog.' Usage is implied for FX rate queries only, with no guidance on exclusions or prerequisites.

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, and the description adds meaningful behavioral context: historical geometry is returned first, an evidenced successor appears only as a separate question and is never fetched automatically, and the response includes metadata, vintage, centroid, bounding box, and optional GeoJSON polygon. This goes well beyond the annotation and describes the tool's actual behavior.

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 and front-loaded: it states the core purpose first, then return content, then behavior, then alternatives, then usage preference. Every sentence earns its place, and there is no redundant restatement of the tool name or title.

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?

Even without an output schema, the description explains the return values (metadata, vintage, centroid, bounding box, optional polygon), key behavioral edge cases (historical first, no successor substitution), exclusions (hierarchy/crosswalks), and usage preference (bbox/centroid over polygon). With a fully documented input schema, this is complete enough for an agent 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 description coverage is 100%, so the schema already documents the parameters. The description adds useful semantic context by explaining that loc_ids can come from any level of a resolve_point chain and that the polygon is optional, reinforcing the include_polygon parameter's role. It does not deeply elaborate every parameter, but it meaningfully supplements the schema.

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

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

The description uses a specific verb and resource: "Shape retrieval for exact loc_ids," including loc_ids from any level of a resolve_point chain. It also distinguishes itself from loc_id_info by explicitly stating what it does not explain, so an agent can tell it apart from nearby siblings.

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

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

The description gives explicit guidance on when to use it: prefer bbox/centroid unless exact rendering or clipping requires the polygon, and use loc_id_info for hierarchy or crosswalk details. It also clarifies that successors are never substituted automatically, which prevents incorrect invocation assumptions.

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 useful behavioral context by specifying that only completed inline jobs are retrievable under the current public contract, while durable queued jobs and downloadable artifacts remain unsupported. This enriches 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 two sentences: the first states the core action with precision, the second provides a clear contract limitation. No unnecessary words or redundancy.

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

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

For a simple read-only status tool with full schema coverage and a read-only annotation, the description is largely sufficient. It covers purpose and contract limitations, but the lack of an output schema means a brief note on return value would be useful, and the term 'bounded v0' is somewhat cryptic.

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%, setting a baseline of 3, but the description adds meaning by requiring job_id to be a completed 'bounded v0' job, which goes beyond the schema's simple origin reference and clarifies expected job state. request_id is already well-documented in the schema.

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

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

The description uses the specific verb 'Retrieves' and clearly identifies the resource as 'completed bounded v0 geometry export or conversion job' accessed 'by job_id'. This distinguishes it from sibling creation/estimation tools such as create_geometry_export and create_conversion_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 implies usage for retrieving completed inline jobs and explicitly notes that durable queued jobs and artifact links are future capabilities, which sets expectations. The schema also references create_geometry_export and create_conversion_job as job_id origin points, but the description itself does not explicitly state when to use or avoid this tool 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 indicate readOnlyHint=true. The description adds that it calls the USGS API and normalizes to DaedalMap event fields. This is useful context but does not significantly expand beyond what the annotation already conveys. No contradictions.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence serves a clear role. It is 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?

The description, combined with the schema and annotations, provides sufficient context for a read-only tool with 11 well-described parameters. It explains the source and normalization, and the usage guidance is clear. Lacks details on output format, but that may be covered by the DaedalMap event field standard.

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 does not add any additional parameter information beyond what is already in the schema; it relies on the schema's 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 that this tool retrieves live/preliminary earthquake events from the USGS FDSN API and normalizes them. It explicitly distinguishes itself from the canonical earthquake lane, making the purpose specific and unambiguous.

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

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

The description explicitly tells when to use this tool (when live/preliminary results are needed or for a very recent window) and what it is not (the enriched canonical history lane). Although it does not name the alternative, the sibling tool get_earthquake_events is implied as the canonical one.

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 that it calls an external WFS service, returns preliminary data, and is not canonical. This provides extra behavioral context 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?

The description is two sentences: the first explains the action and source, the second clarifies its scope. It is front-loaded with the core purpose and uses no unnecessary words.

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

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

The description explains the data source and nature (live, preliminary) but does not describe the returned fields or structure. With no output schema and 8 optional parameters, more detail on the response would improve completeness.

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% description coverage with clear parameter descriptions. The tool description does not add additional meaning beyond what the schema provides, so 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 states it is a live wrapper for volcanic eruption updates from the Smithsonian/GVP WFS, specified to be preliminary and not the enriched canonical history lane. This effectively distinguishes it from sibling tools like get_volcanic_activity.

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

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

The description implies this is for live, preliminary data by stating it's a 'free live wrapper' and 'not the enriched canonical history lane,' but it does not explicitly name alternatives or provide when-not-to-use 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, so safety is covered. The description adds meaningful behavioral context by enumerating what the tool exposes (metadata, coverage, freshness, canonical tool guidance, first-query examples) and the practical benefit ('time shape, coverage limits, and the paste-ready first query'). This explains the output's role without contradicting the read-only 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 with zero redundancy. The first sentence front-loads the purpose and output contents; the second delivers actionable usage guidance. 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 single-parameter, read-only discovery tool with no output schema, the description fully specifies what the agent receives (the enumerated output elements) and when to call it. Nothing an agent needs to invoke it correctly is missing.

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

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

The schema already documents pack_id completely with 100% coverage, including its source (get_catalog) and a note about catalog-admitted packs. The description does not add any additional meaning about the parameter itself, so per the baseline for high schema coverage, a 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 states a specific action ('Returns detailed metadata, coverage, freshness, preferred canonical tool guidance, and first-query examples') targeting a distinct resource ('one pack'). It explicitly frames this as 'Free discovery,' which clearly distinguishes it from sibling tools like query_dataset or get_catalog by its discovery-oriented purpose.

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 an explicit when-to-use instruction: 'Call this before querying a new pack.' This is a clear situational trigger. It does not mention when not to use it or name specific alternatives, but the guidance is unambiguous and actionable for an agent.

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 indicates a safe read operation. The description adds useful behavioral context by stating it returns guidance content and references a shared interaction contract, without contradicting the annotation.

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

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

The description is concise and mostly front-loaded, but contains some dense jargon like 'blind-caller' and 'natural-language-to-strict-JSON interaction contract.' It earns its place with practical guidance and a clear call-to-action.

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?

Without an output schema, the description thoroughly covers what the tool returns, including usage context, example, access limits, outputs, provenance fields, recommended next calls, and the interaction contract. It also provides a clear invocation workflow.

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 a clear parameter description ('Exact tool name from tools/list'). The description reinforces the need to use tools/list but does not add substantial semantic meaning beyond the schema.

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

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

The description clearly states that this tool provides guidance for another tool on the MCP facade, listing the specific types of information returned. It distinguishes itself from the many domain-specific sibling tools by being a meta-tool for unfamiliar-tool assistance.

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 guidance: use tools/list to discover names, then call this before an unfamiliar tool. This clearly states when to use the tool and implies it is not needed for familiar 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?

Disclosure of payment mechanism (HTTP 402 with price before charge), region filter specifics (ISO3, water loc_ids, deprecated XOO), and guidance on limit usage. All beyond readOnlyHint 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?

Three sentences cover purpose, usage, and important details. Efficient but slightly dense; could be more structured. Still concise.

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?

Covers payment, filter usage, limit advice, and metric examples. No output schema, but description implies return values. Adequate 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?

Adds valuable context to parameters: region filters with examples, limit usage with sorting advice, and metric examples. Schema coverage is 100%, so baseline is 3, but description significantly enhances understanding.

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?

Clearly states it queries tsunami events for historical records and water-height/runup metrics. Specifies use cases: event counts, max water height thresholds, top-event lookups. Distinguishes itself from sibling tools by focusing on tsunamis.

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 scenarios and mentions payment requirement. Does not explicitly state when not to use or list alternatives, but context is clear given sibling tool names.

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. The description adds 'Free canonical tool' and 'Queries' but does not disclose any behavioral traits beyond what the annotations provide (e.g., no mention of rate limits, data freshness, or pagination). Minimal added 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 short sentences, each contributing unique information: tool classification, resource queried, use cases, and filter hint. No redundancy or wordiness. Front-loaded with key purpose.

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 good purpose and usage guidance, the description lacks information about return format or output structure, which is critical given no output schema. Also does not mention pagination, data limits, or error conditions for a tool with nested objects and required 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?

The input schema has 100% description coverage, so baseline is 3. The description adds a usage hint about year-style time filters, but this aligns with the schema parameter descriptions (which already mention year-based time ranges). No significant added meaning beyond the schema.

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

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

The description clearly states it queries historical eruption records and volcanic activity metrics, with specific use cases like eruption counts and VEI thresholds. However, it does not explicitly distinguish itself from the sibling 'get_live_volcano_events', missing a clear differentiator.

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 guidance on when to use (best for eruption counts, VEI thresholds, top-event lookups) and a specific filter hint (year-style time filters). Lacks explicit exclusion of live events or alternatives, but the guidance is useful.

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 establishes that this is a safe, non-mutating operation. The description adds useful context beyond that: it reveals the tool teaches durable concepts, provides current catalog coverage, and explains how behavior scales across countries. 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 rich but not bloated; it front-loads the tool's purpose and sequencing, then provides concrete catalog data that helps an agent decide whether to call it. It earns its length by communicating scope, coverage, and next steps efficiently.

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

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

Given that this tool has only one optional parameter, no output schema, and read-only annotations, the description is complete for selection and invocation. It explains what concepts will be learned, which countries have extra depth, and what to do after calling this tool. Nothing essential for an agent is missing.

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

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

Schema description coverage is 100%, since the optional 'question' parameter is fully described in the schema as a natural-language question about the geometry tool family. The tool description adds no additional parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a starting guide for the geography/geometry MCP and explicitly instructs the agent to call it first. It distinguishes itself from sibling tools by positioning itself as the conceptual entry point before read_geometry_catalog or get_tool_help.

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 sequencing: call this first, then read the live geometry catalog for country-specific details, then use get_tool_help for one exact tool. This provides clear usage context and names alternatives, leaving little ambiguity about when this tool should be invoked.

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, it discloses input-handling requirements (preserve leading zeros, no prose in arguments), bounded sample behavior, and the full set of outputs including ranked candidates, deterministic warnings, clarification questions, and recommended geography_binding. It also notes cost ('Free... No payment required') and limitations.

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, but contains a minor redundancy: 'Free geography utility' and 'No payment required' say the same thing. All other sentences earn their place, covering purpose, usage, output, and exclusions.

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 no output schema, the description thoroughly covers return behavior (ranked candidates, warnings, clarification questions, counts, recommended binding), scope limits, and cost. It is complete for a complex identification tool with 6 parameters and nested objects.

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 (83%), so baseline is 3; the description adds actionable parameter guidance not in the schema: LLM clients must extract identifiers from natural-language and pass them as strings, preserve leading zeros, and not put prose in arguments. This complements the schema's existing field 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?

Clearly states it 'Checks a bounded sample of identifiers against maintained reference indexes and geometry banks,' with a specific use case ('unsure which system, level, or bank they belong to') and explicit exclusions ('does not convert the full dataset or return polygons'), distinguishing it from conversion and geometry 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?

Gives explicit when-to-use guidance ('Use it when a caller has geography keys but is unsure...') and when-not ('It does not convert the full dataset or return polygons'). It also provides concrete LLM client instructions for extracting identifier strings, which is valuable operational 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 provide readOnlyHint=true, so the description doesn't need to emphasize read-only. The description adds behavioral context: it mentions 'Free geography utility' (no payment), 'Public calls never expose WIP or relationship-only records' (privacy/filtering), and that read_wip is for operator review. This adds non-obvious details beyond the annotations, such as the concept of WIP records and the loopback-only restriction. However, it doesn't specify pagination or response structure, which could be useful but the annotation covers safety.

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, information-dense, and front-loads the core purpose. It lists many specific data attributes (row counts, vintages, target levels) which adds length but is relevant. It could be slightly more concise by trimming some enumerations, but it 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?

Given the tool is a read-only listing/directory function with annotations covering safety, the description provides a complete picture: what it returns, what filters to use, what it excludes, and when to call it. There is no output schema, so the description must convey the return concept, which it does by listing the kinds of artifacts. The description covers the essential guidance an agent needs to invoke 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 description coverage is 100%, so each parameter is described in the schema. The description adds practical guidance: 'Pass country_scope whenever the country is known' and explains read_wip is for operator review. It doesn't heavily elaborate on parameters but provides context that helps the agent decide how to use them, such as country_scope for focused answers and include_crosswalks default. Since the schema already covers semantics, the extra guidance pushes it above baseline 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 clearly states the tool reads a 'canonical crosswalk registry' and lists published, callable geographic reference systems, crosswalk artifacts, row counts, vintages, etc. It explicitly mentions the types of identifiers (ZIP/ZCTA, postal, census, etc.) and states its purpose: to learn whether identifiers can be exchanged through loc_id. This is specific and distinct from siblings like identify_reference_system or 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 explicitly says 'Pass country_scope whenever the country is known' and 'Call this first to learn whether...' providing clear when-to-use guidance. It also notes public calls never expose WIP or relationship-only records, which implies usage restrictions. It does not name specific sibling alternatives but provides enough context to distinguish this as an initial discovery tool.

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 provide readOnlyHint=true, but the description enriches the behavioral picture considerably: supersession is never automatically substituted, historical records are only returned as requested, and parent edges are never invented across mixed releases. It also discloses the 'No payment required' policy, which is useful operational 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 dense yet well-structured: it opens with the tool's role, then input modes, then output contents, then flag semantics, then sibling differentiation and alternatives. Every sentence contributes distinct information, and the text stays readable despite covering a complex 11-parameter tool.

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 11 parameters and no output schema, the description covers the essential context: how to supply inputs, what the key flags do, what output categories to expect, and when to use sibling tools. The behavioral constraints around supersession and mixed releases are also included. Nothing critical for a correct first call appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic depth beyond individual property docs. It explains the relationship between loc_id and loc_ids, clarifies that include_hierarchy returns the 'strict same-release ancestor chain', and ties include_references to external crosswalks. This helps an agent understand parameter intent, not just types.

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 and resource: a 'drill-down tool for loc_ids' that retrieves metadata, parentage, shape status, vintage/lifecycle fields, and child counts. It further distinguishes itself from siblings by noting 'resolve_point intentionally stays compact' and naming get_geometry and compare_geographies as alternatives. The purpose is unambiguous and clearly differentiated.

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 states when to use the tool: pass one loc_id or the stack loc_ids from resolve_point, and enables hierarchy/references via flags. It also gives clear exclusion guidance: 'For exact polygons use get_geometry, and for overlap or successor analysis use compare_geographies.' This leaves no ambiguity about when to select this tool versus 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 mark the operation as read-only (readOnlyHint: true), and the description aligns by calling it a 'query'. It adds useful context beyond annotations by distinguishing free versus paid packs and mentioning the payment token (x402 Base USDC), which is a behavioral nuance about access costs, not just read-only safety.

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 relatively long due to the enumerated pack list, but every sentence carries useful information: the purpose, the API contract, and the available free/paid packs. The main purpose is front-loaded, and the pack list serves as a quick reference, making the length justified.

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 8 parameters and no output schema, the description provides valuable context by listing all pack identifiers, which is essential for using pack_id. However, it does not describe the response format or any constraints of the 'same contract' beyond the mention, leaving the agent to infer return behavior. This is a notable gap given no 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 schema already documents all parameters with descriptions. The description adds minor context by emphasizing the source_id/pack_id dichotomy, but it does not deepen parameter meaning beyond what's in the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'generic structured query' for 'direct source_id or pack_id access', which is a specific verb and resource. It distinguishes itself from the many specific sibling tools (e.g., get_earthquake_events) by being the generic query pathway, and even references the API contract for precision.

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

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

The description implies usage when you have a source_id or pack_id, and provides a list of valid packs, which gives context. However, it does not explicitly state when to prefer this over sibling tools or when not to use it, leaving some inference to the agent.

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 aligns with that, adding that it is read-only and free. It discloses the default behavior (excluding staged/candidate work) and the read_wip restriction (denied for hosted/public). This is useful context beyond the annotation, though it doesn't describe error behavior or response structure.

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

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

The description is moderately long, with a clear opening sentence and useful guidance. However, the 'Current catalog' paragraph includes promotional details (e.g., 'The same geography tools work worldwide...') that are not essential for invocation and could be trimmed. The information is front-loaded reasonably well.

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 read-only and has no output schema, the description provides sufficient context for an agent to invoke it correctly: it explains the default scope, available view categories, the read_wip limitation, and examples of enhanced country coverage. It doesn't specify exact output format, but for a catalog listing that may be acceptable. The limit parameter is mentioned in schema, and the description gives enough to call it.

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

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

Schema coverage is 100%, so the parameter semantics baseline is 3. The description adds value by explaining the intended order of views (capabilities first), the purpose of read_wip, and implicitly linking country_scope to the capabilities view. It does not redefine parameter types, but it gives usage guidance that the schema does not fully convey.

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 reads the published DaedalMap geometry catalog projection by default, excluding staged and candidate work. It distinguishes from geometry-specific operations by emphasizing 'discovery' and 'catalog', though it does not explicitly name sibling alternatives like get_geometry or get_catalog. The purpose is specific and actionable.

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 strategy: '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 gives a constraint (read_wip only for local loopback MCP) and notes no payment required. It does not explicitly mention when to choose this over siblings, but the intended selection criteria are 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?

Beyond the readOnlyHint annotation, the description adds behavioral constraints: 'strict hierarchy traversal', 'coherent parent chain', and 'must not bridge release seams.' It also clarifies that 'No natural-language decoding is performed,' which is valuable context for callers. These details significantly enrich the safety and usage 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?

Four sentences, each earning its place: function, non-goals, use case, and a behavioral caveat. No redundant or promotional language. The description is front-loaded with the core purpose and immediately gives actionable context.

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

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

The tool has nested scope objects and 8 parameters, but the schema already documents them well. The description explains the core use case and exclusion behavior. It could optionally mention output structure, but the schema's mention of 'rows', 'counts', and 'limit' covers that. Slightly more could be said about when the scope object is preferred, but overall 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?

Schema coverage is high (88%) with informative descriptions for parent_loc_id, admin_level, limit, count_only, etc. The description reinforces the key parameters by naming them ('parent loc_id and target admin level') and adds the no-NL note, which clarifies that admin_level expects structured values. This is a slight value-add over the schema.

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

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

The description states a specific verb and resource: 'returns descendants from that coherent parent chain' given a parent loc_id and target admin level. It distinguishes itself from the 'mixed-vintage latest-per-depth point resolver' (likely resolve_point), making its purpose unique among siblings.

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

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

Explicitly states when to use: 'Use it before shape exports such as every county in a selected parent scope.' Also states what it is not: 'not the mixed-vintage latest-per-depth point resolver' and 'must not bridge release seams.' This gives clear guidance on alternatives and placement in workflows.

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?

Despite readOnlyHint=true already covering safety, the description adds meaningful behavior: row contents, exclusions, small-vs-bulk limits, anonymous vs verified throughput, and automatic depth by catalog coverage. I deduct a point because the stated 25-point cutoff conflicts with the schema's 100-point exploratory allowance, weakening trust in the behavioral contract.

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?

Front-loaded with the core action and output, then organized into exclusions, sibling routing, batching rules, and catalog context. Long, but each block earns its place and the catalog paragraph gives necessary context for expected admin depth.

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 complex 9-parameter tool with no output schema, and the description explains return-row fields as loc_id, name, admin level, and vintage. However, it omits the exact response structure/ordering and contains the 25-vs-100 inconsistency, so an agent does not yet have everything needed to invoke it with certainty.

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 does add practical context around country_scope/target_admin_level and bulk_preset, but its threshold rule conflicts with the schema ('above 25' vs 'up to 100 exploratory points'), so it does not reliably clarify parameter behavior beyond the schema.

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

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

Opens with 'Compact reverse geocoding' and states it converts one WGS84 point or a bounded point list into a latest-available administrative loc_id chain. It differentiates itself by explicitly listing what it does not return (polygons, hierarchy analysis, references, etc.) and pointing to sibling tools that cover those needs.

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 explicit routing: pass stack loc_ids to loc_id_info, use get_geometry for shapes, compare_geographies for relationships, and bulk_preset for cross-country admin-0/admin-1 batches. It also states the batching rule and the need to split multi-country input per country.

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 indicates a safe read operation, so the bar is lower. The description adds useful behavior: output includes ranked loc_id matches with bridge vintage, overlap weights, and provenance, and historical values are not automatically replaced by successors. This goes beyond what annotations provide.

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 purpose is front-loaded and the examples are compact and useful. There is minor redundancy: 'Free geography utility' and 'No payment required' convey nearly the same information, and the historical-reference sentence could be tighter, but overall the description 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 readOnlyHint annotation and a 100%-covered schema with 13 parameters, the description covers the essential behavioral context: it explains the conversion, gives examples, and describes the return fields (ranked matches, bridge vintage, overlap weights, provenance). It does not describe pagination or response structure, but the schema and annotation carry much of the needed load.

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 baseline is 3. The examples in the description (from_system='zip' value='00601', from_system='nws_fire' value='AKZ317') largely repeat examples already present in the schema, so the description adds only minimal parameter-level meaning beyond the input schema.

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

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

The description states a specific action (converts one value or a bounded list into the DaedalMap loc_id universe) and names the exact resource and outcome. The concrete examples for zip, nws_fire, and admin_boundary clearly distinguish this from siblings like convert_reference or identify_reference_system.

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: resolving external or adjacent geographic values into loc_id. It also notes that historical references are returned as requested and that an evidenced successor is never substituted automatically, which is an implicit when-not. However, it does not explicitly name sibling tools or state when to prefer them over this tool.

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 'Free linked-disaster discovery helper' and mentions searching published families, but does not detail search algorithm or output format. With annotations, this is adequate; no additional behavioral disclosure needed.

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-loading purpose and usage. No redundant or extra words. Every sentence 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?

Despite no output schema, the description is sufficient for a discovery tool with 7 optional parameters. It covers purpose and usage context. Slightly incomplete regarding output nature, but acceptable given the tool's simplicity and annotations.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description mentions 'event-type direction, optional via-event type, and optional year window,' which maps to start_event_type, end_event_type, via_event_type, year_start, year_end, but adds no new meaning beyond the schema. 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?

Description clearly states the tool's function: 'Searches published cross-disaster link families' with specific parameters (event-type direction, optional via-event type, year window). It distinguishes from siblings like 'get_disaster_link_chain' (which requires an exact event ID) by focusing on discovery before having an exact ID.

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

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

Explicit guidance: 'Use this when you want to discover whether a relationship family exists before you have an exact event id.' This indicates the usage context and implies alternatives (e.g., get_disaster_link_chain for known IDs), but lacks explicit exclusions.

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