DaedalMap Disaster and Geospatial Data

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: it is fast ('Fast'), scope-limited ('bounded loc_id list'), reports geometry vintage, and emphasizes it is a preflight (no side effects). It also discloses the 'shape-only' limitation, which is not evident from annotations alone.

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

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

The description is three sentences, front-loads the core purpose, and every sentence contributes unique value: what it does, what it reports, its usage context, and cost/limitations. No wasted words or repetitive content.

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

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

Despite the lack of an output schema, the description clearly explains the tool's return concept ('reports whether each exact identity has reusable geometry and its geometry vintage'), which is sufficient for an agent to understand the expected output. It also provides performance, cost, and usage context, making it a complete picture for a preflight 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?

The input schema already provides 100% coverage with clear descriptions for all four parameters, so the description adds minimal parameter-specific meaning. The phrase 'bounded loc_id list' is slightly informative but the schema already mentions the deployment-configurable cap, so the description does not significantly elevate 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?

The description clearly states a specific action (preflight check) on a specific resource (loc_id geometry), and distinguishes itself from sibling tools by explicitly noting it does not resolve points or explain identity relationships. The phrase 'shape-only preflight' encapsulates the tool's unique role.

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

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

Explicit guidance is provided: 'Use before get_geometry or an export.' The description also clarifies what the tool does NOT do (resolve points, explain relationships), which helps agents avoid misusing it for those purposes. 'No payment required' adds a relevant usage consideration.

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 already declare readOnlyHint=true, so the safety profile is known. The description adds useful behavioral context: it lists the return contents (metadata, vintage, centroid, bbox, optional polygon), notes it includes resolve_point chain levels, and clarifies it does not explain hierarchy. 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?

Four sentences, front-loaded with the core purpose, followed by return details, exclusions/alternative, and usage preference. Every sentence earns its place without redundancy or fluff.

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

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

For a read-only shape retrieval tool with no output schema, the description covers the essential outputs, the scope of loc_ids, exclusions, and a usage preference. It does not mention pagination or rate limits, but the schema already documents the batch cap, so the description remains sufficiently complete for selection and invocation.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds value by directly relating include_polygon to the choice of bbox/centroid vs. exact rendering, and clarifies the optional polygon behavior. It also mentions the default public cap indirectly via 'No payment required' and the schema handles cap details.

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 ('Shape retrieval') and resource ('exact loc_ids'), also clarifying it works for any level of a resolve_point chain. It distinguishes itself from loc_id_info by stating it does not explain hierarchy or crosswalks, making the tool's purpose easy to identify 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?

Provides explicit guidance: use loc_id_info for hierarchy/crosswalk details, and prefer bbox/centroid unless exact rendering or clipping requires the polygon. This clearly states when to use this tool versus alternatives and when to select specific output options.

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 annotation readOnlyHint=true already signals the tool is safe to call without side effects. The description adds behavioral context by explaining that this is an introductory guide, not a data operation, and provides current catalog scope details. It does not contradict the 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 front-loaded with the most important guidance ('Call this first') and then supplies a compact learning path. The catalog detail is relevant and not redundant, and every sentence contributes useful context for invoking the tool correctly.

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 one optional parameter and no output schema, the description gives enough guidance to know when and how to call it, what concepts it introduces, and what to do next. It does not specify the exact return format, but for a guide-style tool this is a minor gap.

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 only parameter, 'question', is fully documented in the schema as an optional natural-language question. The description itself does not elaborate on the parameter, but schema coverage is 100%, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool as a free starting guide and explicitly instructs the agent to 'Call this first' to learn the geometry/geography concepts. It also distinguishes this tool from siblings by placing it first in the learning sequence and pointing to get_tool_help for individual tool details.

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 an explicit usage sequence: call this tool first, then read the live geometry catalog, then use get_tool_help for a specific tool. This makes when-to-use and the relationship to sibling tools unambiguous.

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

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

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 already declare readOnlyHint=true, and the description is consistent with that, adding further behavioral context: 'No payment required,' the include_hierarchy behavior of never inventing a parent edge across mixed releases, and the distinction between strict parentage and external side-chain references. This goes beyond the structured annotation and helps the agent predict side effects and access implications.

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 earns its place: input shape, returned data, optional flags, sibling routing, and cost/access note. There is no filler or tautology.

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

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

For an 11-parameter tool with no output schema, the description covers the essential invocation semantics, the main flags, the expected return categories, and the relationship to sibling tools. The schema covers parameter-level details, while the description supplies the contextual framing an agent needs to choose and call this 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 baseline is 3. The description adds value by clarifying how loc_ids relate to a resolve_point stack and by explaining the real effect of include_hierarchy and include_references in plain chain-explanation terms. It does not need to repeat the schema; it adds the grouping and flag semantics that schemas often leave implicit.

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

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

The description opens with a specific verb and resource: it is the 'drill-down tool for loc_ids returned by resolve_point and other geography calls.' It names the exact data returned—metadata, parentage, shape status, vintage/lifecycle, child counts—and distinguishes itself from get_geometry and compare_geographies, 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?

It gives explicit invocation guidance: pass one loc_id or pass the point result's stack loc_ids together. It also says when to use alternatives—'For exact polygons use get_geometry, and for overlap or successor analysis use compare_geographies'—and notes that resolve_point intentionally stays compact, making the trade-off between siblings 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 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?

The annotations already declare readOnlyHint=true, and the description reinforces that by saying 'Reads'. It adds critical behavioral details: exclusion of staged/candidate work, local-loopback-only read_wip access, and automatic return of deeper tiers for additional country releases. It also states 'No payment required', a cost-related behavior. No contradiction with annotations.

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

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

The description is quite verbose, with promotional language like 'Free geography discovery' and an entire paragraph on catalog scope ('Current catalog:...') that is not essential for calling the tool. Key usage instructions appear early, but the later marketing content dilutes focus. It could be trimmed by half while retaining all required actionable information.

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

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

The description covers the core behaviors needed to use the tool: default projection, exclusion of staged/candidate, view guidance, and access restriction for read_wip. It also provides context on country coverage. However, it lacks a clear statement of what the response contains, and includes redundant marketing content. Overall, it is sufficient but not lean.

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 covers all 5 parameters with detailed descriptions, achieving 100% coverage. The description adds context around view usage (e.g., 'use view='capabilities' first') and read_wip restrictions, but these are largely redundant with the schema's own descriptions. It does not clarify parameter formats or constraints beyond what the schema already provides.

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

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

The description clearly states a specific action: 'Reads the published DaedalMap geometry catalog projection' and notes it excludes staged/candidate work. It distinguishes from other catalog tools by specifying 'geometry catalog projection', though it does not explicitly contrast with get_catalog. The scope is unambiguous.

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

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

The description provides explicit guidance on which view to use first ('Use view='capabilities' first') and mentions focused views for different artifact types. It also notes the read_wip constraint for local loopback access. However, it does not explain when to choose this tool over siblings like get_catalog or get_geometry, leaving some selection ambiguity.

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

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

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?

Annotations only declare readOnlyHint=true, so the description carries the full burden. It discloses compact output shape, exploratory vs. batch limits, country_scope and target_admin_level requirements, payment for anonymous callers above 25 points, verified-account throughput through 10,000 points, and catalog coverage depth. This is rich, non-obvious behavioral context well 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?

Long but information-dense; every sentence adds a constraint, alternative, or behavioral detail. It is not tightly concise, but it is logically structured and front-loaded with the core function and key limitations before catalog 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?

With no output schema, the description compensates by explaining the return chain contains loc_id, name, admin level, and vintage, and explicitly enumerates omitted features. It also covers limits, payment, geographic coverage, and alternative routing, making it very complete for a complex 9-parameter tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning by explaining exploratory vs. batch behavior and how country_scope, target_admin_level, and bulk_preset relate. Minor deduction: the description says the 25-point preview limit while the schema says country_scope is optional for up to 100 exploratory points, which creates a slight inconsistency.

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: 'Converts one WGS84 point, or a bounded point list, into the latest-available administrative loc_id chain.' It also distinguishes itself from sibling tools by explicitly listing what it does not return (polygons, hierarchy analysis, references, overlap percentages, etc.) and pointing to alternative tools for 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?

Provides explicit routing guidance: pass loc_ids to loc_id_info for details, use get_geometry for shapes, compare_geographies for relationships, and bulk_preset for cross-country admin-0/admin-1 batches. This gives an agent clear conditions for selecting 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 declare readOnlyHint=true, so the tool is known to be read-only. The description adds meaningful behavioral context: it returns 'ranked loc_id matches with bridge vintage, overlap weights, and provenance where applicable,' and notes 'No payment required,' which goes beyond the annotation. It does not disclose limitations like rate limits or error handling, but the annotation covers the safety profile.

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

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

The description is extremely concise—two sentences—and front-loads the core purpose with a clear verb and resource. The examples are packed into the first sentence without wasting words, and the second sentence covers output and cost. Every sentence earns its place; there is no fluff.

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

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

Despite having 13 parameters and no output schema, the description adequately covers the tool's purpose, input format, and output nature ('ranked loc_id matches with bridge vintage, overlap weights, and provenance'). It does not explain the interaction between parameters (e.g., when to use items vs value), but the schema's anyOf and parameter descriptions handle that. The description is sufficient for an agent to understand what to call and what to expect.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters with detailed descriptions. The description adds value by providing concrete examples of from_system and value pairs (e.g., 'zip'='00601'), which illustrate the expected format and are not in the schema itself. This extra context justifies a score above the baseline of 3.

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

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

The description clearly states a specific verb ('converts'), a precise resource ('external or adjacent geographic reference system into the DaedalMap loc_id universe'), and provides concrete examples ('zip' value='00601', 'nws_fire' value='AKZ317', 'admin_boundary' value='Fairfax County'). This makes the tool's function unambiguous and distinguishes it from sibling conversion tools like convert_reference.

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

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

The description gives usage examples but does not explicitly state when to use this tool over its siblings, such as convert_reference. There is no 'when to use' or 'when not to use' guidance, no mention of exclusions, and no alternative tools are referenced. The examples imply usage, but the guidance is only implicit.

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

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

Annotations already 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.