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 description does not need to restate safety. It adds useful context about the bridge mechanism (X -> loc_id -> Y), the bounded-list nature, and that no payment is required. It lacks rate-limit or error-behavior details, but with annotation coverage, the added context is sufficient.

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

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

The description is four short sentences with no redundancy. It front-loads the core purpose, then adds use cases and the free aspect, all of which earn their 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?

With 11 parameters and no output schema, the description covers purpose, use cases, and the two modes (single vs. list), but does not explain return-value shape or error handling. The schema hints at ranked outputs via limit/min_share, yet the description itself leaves those details to the schema, which is a moderate gap for a complex tool.

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

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

Schema coverage is 100%, with every parameter having a description, so the description does not need to compensate. It adds general context about the conversion path but no parameter-specific detail beyond schema descriptions, meeting the baseline for well-documented schemas.

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 converts one or a bounded list of geographic references between systems, with a specific mechanism (resolving through DaedalMap loc_id chain). It also gives concrete workflow examples, distinguishing it from siblings like resolve_reference or 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?

Provides explicit use cases such as ZIP/ZCTA to NWS fire zones and NWS zone to counties, making the intended context clear. However, it does not explicitly mention when not to use it or compare with alternatives like create_conversion_job, so it stops short of full when/when-not guidance.

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

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

The annotation readOnlyHint=false already indicates a write operation, but the description adds important behavioral context: batch size determines whether the operation completes inline or returns a queued job_id for artifact processing and polling. This goes beyond the annotation and provides key information for agent planning, though it does not disclose side effects, auth requirements, or error conditions.

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

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

The description is two sentences, front-loaded with the action, and contains no filler. Every phrase earns its place: 'accepted' signals prerequisite validation, and the batch-size distinction is essential. It is appropriately sized for the tool's complexity.

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 partially explains what to expect (job_id for large batches) but omits the return value for inline cases. It does not mention the expected workflow with estimate_conversion_job or get_job_status by name, leaving the agent to infer the overall process. Given the tool's 6 parameters and absence of an output schema, the description provides a useful but incomplete picture.

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 67% (4 of 6 parameters have descriptions), so the schema bears most of the burden. The description adds minimal parameter-level meaning: it references 'items' indirectly via batch size (small vs larger batches) but does not explain from_system, to_system, target_admin_level, or the relationship between quote_id and estimate_conversion_job. It meets the baseline but does not elevate it.

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 ('Creates') and resource ('accepted user-data conversion job'), and adds scope by distinguishing inline completion for small batches vs queued job_id for larger batches. It effectively differentiates from sibling tools like estimate_conversion_job by focusing on the actual creation step, and its two-sentence structure is more informative than a generic update tool.

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

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

The description implicitly communicates usage context: use this to convert user data, with behavior depending on batch size (inline vs queued). However, it does not explicitly name alternatives or exclusions (e.g., 'use estimate_conversion_job first' or 'for direct reference conversion use convert_reference'). It hints at status polling but stops short of directing the agent to get_job_status.

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 are minimal (only readOnlyHint=false), so the description carries the burden. It discloses the async/queued behavior (inline vs job_id) and the negative scope ('does not define or publish'). It does not mention auth, rate limits, or side effects beyond creating an export, but the disclosed behavioral traits add significant 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?

The description is two sentences with no filler. The main purpose is front-loaded, and each sentence adds essential information: the creation action and the inline/queued behavior with the negative scope. Highly concise and well-structured.

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

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

With 7 parameters, a nested scope object, anyOf constraints, and no output schema, the description is somewhat sparse. It explains the core selection modes and the queued job behavior, but omits details on scope subfields, format/include_polygon, and the exact inline return shape. It is adequate for a basic understanding but requires more for a new agent to invoke correctly without external knowledge.

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 29% (quote_id and request_id have descriptions). The tool description clarifies the relationship between loc_id, loc_ids, and scope ('exact loc_ids or one strict scope'), but does not explain format, include_polygon, or the structure of the scope object (bbox, admin_level, parent_loc_id). Partial compensation for a low-coverage 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 'Creates a geometry export from exact loc_ids or one strict scope', using a specific verb and resource. It also distinguishes itself from siblings by explicitly noting it 'does not define or publish a canonical geometry release package', clarifying its scope among related tools like create_conversion_job or estimate_geometry_package.

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

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

The description provides useful context: tiny selections complete inline, larger selections return a queued job_id, and it explicitly excludes canonical release package creation. However, it does not name alternative tools or provide explicit when-to-use vs when-not-to-use guidance beyond that single exclusion.

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 a safe, non-destructive operation. The description adds meaningful context with 'Free dry-run quote' and 'before execution', clarifying that no conversion is triggered and no charges are incurred. This goes beyond the annotation by explaining the intended effect on the data and user wallet.

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 entire description is a single, compact compound sentence. It front-loads the key concept ('Free dry-run quote'), then lists exactly what is estimated. No filler or redundant phrasing.

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

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

Given the tool has no output schema, the description adequately summarizes the output contents (rows, resolvability, bytes, errors, charge units). It does not explain the anyOf requirement between items and row_count, nor the target_admin_level parameter, but these are partially covered by the input schema. Overall, it is sufficient for an estimate tool with moderate complexity.

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

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

Schema coverage is high (83%), so parameters are mostly self-explanatory. The description further adds semantics by mentioning 'sample resolvability', implying that the 'items' parameter can contain sample rows for estimation. It also clarifies the overall purpose of the estimate, which helps connect parameters like row_count and items to the quoting workflow.

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 dry-run quote estimator for user data conversion, with a specific verb ('estimate') and scope ('rows, sample resolvability, output bytes, errors, and charge units'). This distinguishes it from siblings like create_conversion_job, which actually executes the 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?

The phrase 'before execution' gives clear context that this tool is meant to be used prior to running an actual conversion job. While it doesn't explicitly name an alternative (e.g., create_conversion_job), the timing implication is unmistakable and provides sufficient usage guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds valuable context by specifying the tool is a dry-run estimate, enumerating what it computes, and clarifying it does not produce a canonical DaedalMap release bundle. This goes beyond the annotation and gives a realistic expectation of the tool's 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 compact (two sentences) and front-loaded with the primary purpose. The second sentence efficiently clarifies the boundary of what the tool estimates. No wasted words or redundant 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?

For a tool with six parameters, nested objects, and no output schema, the description covers the essential purpose, output details, and what it does not do. It does not explicitly tie to sibling export/estimation tools, but the 'dry-run' label and listed outputs make the context reasonably complete. Given the schema enforces input selection, the missing explicit usage guidance is not a critical 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?

Schema descriptions cover 83% of parameters (5 of 6), including format, loc_id, loc_ids, request_id, and include_polygon. The tool description itself does not add parameter-specific guidance or examples beyond the schema, so it does not compensate for the few undocumented parameters (scope). 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 performs a dry-run estimate for a geometry export and enumerates specific output aspects (loc_id count, shape/vintage availability, bytes, delivery mode, citation requirements, charge units). It also distinguishes itself from a canonical DaedalMap release bundle, making it distinct from sibling tools like create_geometry_export.

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

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

The phrase 'dry-run estimate' clearly implies use before executing an actual export, and the note about not being a canonical release bundle adds a mild exclusion. However, it does not explicitly name alternative tools (e.g., create_geometry_export) or provide explicit when-not-to-use guidance, so it falls short of the highest clarity.

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?

The description adds behavioral context beyond the readOnlyHint annotation by listing what the tool returns (progress, errors, callback state, artifact links) and the job statuses it covers. It does not contradict the annotation, and the added detail gives the agent a better understanding of what to expect.

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 concise sentences with no redundancy. It front-loads the core function and then specifies return values, earning every word.

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

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

Given that there is no output schema, the description adequately conveys the return content (progress, errors, callback state, artifact links). It covers the tool's core behavior and is sufficiently complete for a status-checking tool, though it could potentially mention polling behavior or failure scenarios.

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%, meaning both parameters are fully described in the input schema. The description adds no additional parameter semantics, so the baseline 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 states the tool's function: checking queued/running/completed async geometry export and conversion jobs. It uses a specific verb ('Checks') and resource ('async geometry export and conversion jobs'), and this distinguishes it from sibling tools like create_conversion_job and create_geometry_export.

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

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

The description implies usage after creating a job via create_geometry_export or create_conversion_job, and the job_id parameter schema explicitly states where to obtain the job ID. It provides clear context for when to use the tool, though it does not explicitly exclude alternatives or state when not to use it.

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

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

Annotations 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 the description adds value by detailing what is returned (metadata, coverage, freshness, first-query examples) and noting it is free. No contradictions; it provides 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?

Two concise sentences with no wasted words. The description is front-loaded with 'Free discovery' and efficiently conveys essential information about the tool's purpose and usage.

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 adequately explains what is returned: metadata, coverage, freshness, canonical tool guidance, and first-query examples. It covers key aspects like time shape and coverage limits, making it complete for a discovery 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 covers pack_id with 100% description coverage, listing example values. The tool description does not add additional meaning to the parameter beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns detailed metadata, coverage, freshness, canonical tool guidance, and first-query examples for a pack. It uses a specific verb ('returns') and resource ('metadata for one pack'), and distinguishes from siblings like query_dataset by emphasizing discovery before querying.

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 instructs to call this before querying a new pack, providing clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives, though the sibling context implies that query_dataset is for actual queries.

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 context by calling it 'free blind-caller guidance' and listing the categories of returned information. This goes beyond the annotation by clarifying the tool's advisory nature and what it will output.

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

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

Two sentences deliver all necessary information with no fluff. The description is front-loaded with the core purpose and then gives actionable guidance.

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

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

For a simple one-parameter meta-tool, the description is fully sufficient. It covers purpose, usage, what to expect in the output, and the relationship to tools/list, compensating for the absence of an output schema.

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

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

The input schema already fully documents the only parameter (tool_name) with 'Exact tool name from tools/list.' The description reinforces this by mentioning tools/list, but does not add new parameter-level detail. Baseline 3 is appropriate for 100% schema coverage.

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

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

The description uses a specific verb 'Returns' and clearly defines the resource: 'guidance for one tool visible on this MCP facade.' It details the content of the guidance, distinguishing this meta-tool from all sibling data-access tools.

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

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

The description provides explicit usage instructions: 'Use tools/list to discover names, then call this before an unfamiliar tool.' This tells the agent exactly when to use the tool and the prerequisite step, leaving no ambiguity.

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

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

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?

Annotations include readOnlyHint=true, so the safety profile is covered structurally. The description adds useful context by explicitly stating 'Free geography utility' and 'No payment required,' which addresses cost/monetization concerns not captured by annotations. It doesn't describe pagination or volume, but for a listing tool with read-only annotation this is adequate.

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 reasonably sized with a clear front-loaded purpose, a useful content enumeration, and a decisive usage directive. 'No payment required' is slightly redundant with 'Free geography utility' and could be trimmed, but overall every sentence earns its place.

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

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

For a listing tool with readOnly annotation, one optional parameter, and no output schema, the description covers what it lists, when to call it, and cost considerations. It's complete for this tool class. The absence of an output schema is a mild gap but the tool is simple enough.

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% (request_id documented). The single optional parameter is traced in the schema, and the description doesn't contradict or add much beyond it. Baseline of 3 is correct when schema fully handles the only parameter; no compensation needed.

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

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

The description clearly states the verb+resource ('Lists the currently exchangeable geographic reference systems in DaedalMap') and enumerates specific content (geometry families, bridge artifacts, row counts, vintages, target levels, license metadata), distinguishing it from sibling tools like get_catalog and loc_id_info.

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

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

Explicitly states 'Call this first when you need to know whether ZIP/ZCTA, NWS zones, tribal areas, marine ids, NUTS-style regional ids, or other systems can be exchanged through loc_id.' This names concrete use cases, explains the sequencing (call first), and frames it against exchange through a specific identifier.

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

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

Annotations declare readOnlyHint=true, and the description reinforces read-only behavior by describing retrieval of metadata. Adds context about strict parentage and mixed-release behavior, and the note about no payment clarifies a non-obvious aspect. No contradiction.

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

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

Five sentences, front-loaded with purpose, each clause contributes to usage understanding. No fluff; the parenthetical about 'never invents a parent edge' is valuable.

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?

No output schema, but the description enumerates what is returned (metadata, parentage, shape status, vintage/lifecycle fields, child counts) and covers the major optional flags. The only gap is a full response structure, but tool purpose is clear enough for an agent 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 covers all 11 parameters at 100%, so baseline is 3. Description adds semantic depth by explaining include_hierarchy (strict same-release ancestor chain) and include_references (external or side-chain crosswalks), and clarifies the batch/request IDs are for tracing. This enriches 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 identifies the tool as a drill-down for loc_ids, distinguishing it from siblings by naming resolve_point as the compact alternative and get_geometry/compare_geographies for other use cases. Strong verb+resource pairing with explicit scope.

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

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

Explicitly states when to use: 'This is where detailed chain explanation belongs' and provides exclusions: 'For exact polygons use get_geometry, and for overlap or successor analysis use compare_geographies.' Also explains input forms (single loc_id or stack).

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 only readOnlyHint, so the description adds value by disclosing that paid packs require payment (x402 Base USDC) and referencing the API contract. This goes beyond the read-only flag, though it does not cover error behavior or rate limits.

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 compact sentences: the first states purpose and contract, the second lists free and paid packs. No redundant information, front-loaded with the core 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?

Given the tool's complexity (8 parameters, nested objects) and lack of output schema, the description is minimal. It provides useful pack categorization and an API reference, but does not explain return values, discovery of IDs via get_catalog, or query capabilities such as filters and metrics.

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 all 8 parameters completely, so the description adds marginal value beyond that. It does categorize pack_id values into free and paid groups, which aids selection, but does not clarify the relationship/requirement between source_id and pack_id.

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 this is a generic structured query for direct source_id or pack_id access, and lists specific free and paid packs. This distinguishes it from sibling tools like get_earthquake_events or get_tsunami_events that target specific datasets.

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 use for direct ID-based queries and categorizes packs as free or paid, which helps selection. However, it lacks explicit guidance on when to prefer this generic tool over specific sibling getters, and does not mention 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 is a read operation, so the description's main added value is noting that no payment is required and that it returns an agent-friendly catalog view. It adds some usage guidance but does not disclose return format or pagination behavior, so credit is limited.

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 brief and front-loaded with the core purpose, and the usage guidance is efficient. Minor redundancy exists ('Free' and 'No payment required'), but overall it is well-structured.

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

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

For a read-only catalog tool with no output schema, the description covers the main use case and view-selection strategy. However, it does not describe what the different view values return or the shape of the catalog data, leaving some ambiguity for an agent choosing among the enum options.

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

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

Input schema covers all three parameters with descriptions and enum values, so the description does not need to explain them. It reinforces the summary/full view distinction but adds no new detail about limit or request_id 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 the tool reads the DaedalMap geometry catalog and identifies the key content (collections, families, banks, crosswalk products, named reference objects). It uses a specific verb ('reads') and resource, and frames it as a precursor to loc_id tools, but it does not explicitly distinguish itself from the similarly named sibling get_catalog.

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 to use view='summary' first and view='full' only when the whole catalog is needed, and states the tool should be used before choosing loc_id tools. It lacks explicit 'when not to use' or named alternatives, but provides clear context and sequencing.

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?

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: row contents are intentionally small, mixed-vintage chains are context rather than strict parent assertions, and larger batches return a payment-required quote. This goes well beyond what annotations provide.

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

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

The description is dense but well-structured, front-loading the core purpose, then covering output format, exclusions, alternatives, parameter guidance, caveats, and batch behavior. Every sentence adds value, and the length is justified given the tool's complexity and the surrounding sibling ecosystem.

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 is remarkably complete for a tool with no output schema. It covers row structure, lack of polygons and other details, integration points with sibling tools, parameter stopping behavior, and payment implications. It fully equips an agent to decide and invoke the tool correctly.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds minimal parameter semantics beyond the schema: it clarifies target_admin_level ('Set target_admin_level only to stop at a shallower tier') but this largely mirrors the schema text. No additional meaning for lat/lon, points, country_scope, or batch_id is provided.

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

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

The description clearly states the tool's function: 'Compact reverse geocoding. Converts one WGS84 point, or a bounded point list, into the complete latest-available administrative loc_id chain.' It differentiates from siblings by explicitly listing what it does not return and pointing to alternatives like loc_id_info, get_geometry, and compare_geographies.

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

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

The description provides explicit guidance on when to use the tool (for reverse geocoding to loc_ids) and when not, naming specific alternatives for other needs. It also gives conditional advice on the target_admin_level parameter and notes the free preview batch limit, making usage boundaries clear.

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

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

Annotations already declare readOnlyHint=true; the description adds value by detailing return content (ranked loc_id matches, bridge vintage, overlap weights, provenance) and notes the 'bounded list' constraint and 'No payment required'. 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?

Four sentences front-load the core purpose, followed by useful examples. The 'No payment required' line is extraneous but brief; overall efficient and structured, though the examples could be trimmed without losing 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?

Given the 13-parameter schema with full coverage and a readOnly annotation, the description adds key missing context: return format, single vs bounded list input, and cost. It does not explain all optional toggles (as_of, iso3), but the schema covers those, making this adequate for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions for all 13 parameters. The description supplies concrete example values (zip, nws_fire, admin_boundary) but does not add meaningful semantics beyond the schema, so baseline 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?

Description uses a specific verb ('Converts') and clearly states the resource: external or adjacent geographic reference systems into the DaedalMap loc_id universe. Examples with from_system/value pairs further disambiguate from sibling tools like convert_reference 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?

No explicit guidance on when to use this tool instead of alternatives. The description positions it as a 'free geography utility' and gives examples, but does not mention when not to use it or direct users to convert_reference for the reverse direction or resolve_point for coordinates.

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.