DaedalMap Disaster and Geospatial Data

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

Annotations declare readOnlyHint=true, consistent with a read-only utility. The description adds behavioral context: the polygon can be large, so use include_polygon judiciously. It also states 'Free geography utility' and 'No payment required,' which are helpful beyond the structured 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?

The description is four sentences with no wasted words. It front-loads the purpose and default behavior, then adds usage guidance and a note about cost. 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?

Without an output schema, the description adequately explains the return values (bbox, centroid, optionally polygon). It covers the key aspects: what is returned, when to use each, and the cost implication. The complexity is low, and the description is complete enough for an agent to use 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?

Parameter schema coverage is 100%, so the description adds relatively little. However, it provides an example for loc_id ('USA-CA' or 'USA-CA-037') and explains the default behavior of include_polygon (default false to keep responses small), which adds practical 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 the tool returns geographic extent (bbox and centroid, optionally polygon) for a DaedalMap loc_id. It uses a specific verb ('returns') and resource ('geographic extent of a DaedalMap loc_id'), differentiating it from sibling tools like earthquake events or catalog lookups.

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 concrete usage guidance: 'Use the bbox to clip or index your own grid/raster data' and 'request the polygon only when you need the exact perimeter (it can be large).' It also notes 'No payment required.' However, it does not explicitly state when not to use this tool or compare with siblings.

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

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

The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds context by specifying it returns 'live agent-ready data packs', which clarifies the data's readiness state. It doesn't disclose rate limits, authentication needs, or pagination behavior, but with annotations covering safety, this provides moderate additional 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 a single, well-structured sentence that front-loads the key action ('Free discovery') and resource. Every word earns its place, with no redundancy or waste, making it highly efficient and easy to parse.

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 simplicity (0 parameters, read-only annotation, no output schema), the description is adequate but minimal. It explains what the tool returns but lacks details on format, pagination, or error handling. For a discovery tool, more context on output structure would enhance 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?

There are zero parameters, and schema description coverage is 100% (empty schema). The description doesn't need to explain parameters, so it appropriately focuses on the tool's function. Baseline for zero parameters is 4, as it efficiently conveys the tool's purpose without unnecessary param 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 clearly states the tool's purpose with a specific verb ('Returns') and resource ('list of live agent-ready data packs available on DaedalMap'). It distinguishes from siblings by focusing on catalog discovery rather than specific data types like earthquakes or FX rates. However, it doesn't explicitly contrast with 'get_pack' which might retrieve a single pack.

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

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

The description implies usage for discovery purposes ('Free discovery'), suggesting it's for browsing available data packs. However, it provides no explicit guidance on when to use this versus alternatives like 'query_dataset' or 'get_pack', nor does it mention prerequisites or 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?

Annotations already declare readOnlyHint=true. Description adds context that the tool returns a 'bounded related-event chain', which extends beyond annotations. Does not disclose error handling or edge cases, but 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?

Two succinct sentences with no filler. Front-loaded with purpose and usage condition. Every word 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?

No output schema, so description should clarify return format. 'Bounded related-event chain' is vague. Missing details on output structure and effects of parameters like cross_type_only.

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 parameter descriptions. The description adds little beyond what's in the schema, 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?

Description clearly states the tool 'expands one exact disaster event id into a bounded related-event chain', specifying the verb and resource. It also lists supported packs and distinguishes itself from sibling tools by requiring an exact event 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?

Explicitly says to use only when you have an exact event ID from supported packs, providing clear context. However, it doesn't name alternatives like get_disaster_links_for_event or search_disaster_links.

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, and the description adds context about being a 'free linked-disaster helper' and resolving exact IDs. It does not detail failure modes or output format, but the annotation lowers the burden.

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 function statement, concise usage guidance with no 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?

Lacks output schema and does not describe return value structure. Provides adequate context for a read-only tool with well-documented parameters, but return format is missing.

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

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

Schema coverage is 100%, so description adds limited extra value. It reinforces the 'exact event id' constraint but doesn't elaborate beyond 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 clearly states the tool resolves an exact disaster event ID into published related-disaster links, distinguishing it from siblings like search_disaster_links or get_disaster_link_chain.

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 packs) and implies when not to use, though it doesn't name alternatives directly.

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 valuable context about the paid nature (HTTP 402 cost query), cost scaling, and that it is the enriched history lane, which goes 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 brief (3 sentences) with each sentence providing key information: identification, usage guidance, payment behavior. No unnecessary 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?

While no output schema exists, the description focuses on usage and payment, but lacks explicit summary of return data. However, the tool name and schema provide enough context for an agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not provide additional parameter meaning beyond what the schema offers, 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 'Queries the published earthquakes_events lane' and distinguishes it from the preliminary wrapper, making it specific and differentiating from siblings 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 tool first for earthquake questions and explains payment negotiation. It does not explicitly state when not to use, but the sibling context implies alternatives for live data.

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 the trait 'Free tool' and specifies the query granularity options. No contradiction, and it provides additional context beyond what annotations cover.

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 'Free tool' opener is concise, and the main sentence packs functionality efficiently. Every part contributes to understanding.

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?

While the description covers the core functionality, it omits details about return format, pagination, and how to use optional parameters like sort, limit, or output. Given no output schema, more context would be helpful for 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?

Schema coverage is 100%, but the description adds value by explaining that 'filters.region_ids' and 'filters.time.granularity' are key, and that the default metric is 'local_per_usd'. This gives functional meaning beyond the schema's property descriptions.

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

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

The description clearly states the verb 'queries', the resource 'currency pack', and the specific outputs: daily, weekly, or monthly FX data. It distinguishes from sibling tools that cover different data types like earthquakes or volcanoes.

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

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

The description implies when to use (for FX rate data with specific filters) but provides no explicit guidance on when not to use or alternatives among siblings. The usage is inferred from the tool's purpose.

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

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

Annotations indicate readOnlyHint=true, consistent with description. Description adds context about live wrapper and upstream API call but does not mention rate limits, data freshness guarantees, or behavioral traits beyond what annotations already 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?

Three concise sentences with no wasted words. Front-loaded with the essential action, then usage guidance, and final clarification. 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?

With 11 parameters, no output schema, but high schema coverage, the description adequately explains the tool's niche. Could be improved by mentioning typical output structure or pagination, but overall sufficient for an agent.

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

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

Schema coverage is 100% with detailed descriptions for all 11 parameters. Description does not add significant meaning beyond what the schema already provides. 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?

Clearly states it retrieves live/preliminary earthquake events from USGS FDSN API, normalized to DaedalMap fields. Distinguishes itself from the canonical history lane, differentiating from siblings like get_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 specifies when to use: only for live/preliminary results or very recent window not in canonical lane. Clearly states what it is not (enriched canonical history lane), providing direct contrast to sibling 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?

Annotations provide readOnlyHint=true, but the description adds valuable context beyond that: it discloses the data source (Smithsonian/GVP WFS), clarifies it's a 'free live wrapper', mentions normalization to DaedalMap fields, and distinguishes 'preliminary' from 'enriched canonical history'. This gives the agent useful behavioral insights about data freshness and transformation.

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-loaded with the core purpose. Every word earns its place: 'Free live wrapper' sets context, 'Calls the Smithsonian/GVP WFS' specifies source, 'recent preliminary volcanic eruption updates' defines scope, 'normalized to DaedalMap event fields' explains transformation, and the final sentence clarifies what it's not.

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, no output schema), the description provides good context about data source, freshness, and transformation. With annotations covering read-only safety and schema covering all parameters, the main gap is lack of output format details, but the description compensates reasonably with normalization information.

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

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

With 100% schema description coverage, the input schema already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 for high schema coverage without compensating 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 the tool 'calls the Smithsonian/GVP WFS for recent preliminary volcanic eruption updates' and 'normalized to DaedalMap event fields', which is a specific verb+resource combination. It distinguishes from siblings by specifying 'live' and 'preliminary' updates, differentiating from tools like 'get_volcanic_activity' or 'get_catalog', though not explicitly naming alternatives.

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 context by stating 'Free live wrapper' and 'recent preliminary volcanic eruption updates', suggesting it's for current/ongoing events rather than historical data. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_volcanic_activity' or provide clear exclusions beyond 'not the enriched canonical history lane'.

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 provide readOnlyHint=true, indicating no destructive side effects. The description adds value by explaining what the tool returns (metadata, coverage, etc.) and implies it is safe with 'Free discovery'. 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?

Two sentences, no wasted words. Each sentence serves a purpose: what it does and when to use it. Perfectly sized.

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 discovery tool with no output schema, the description lists the key return elements (metadata, coverage, freshness, etc.) and usage context. It is complete enough for an agent to understand the tool's value.

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

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

The input schema has 100% coverage; the description adds minimal additional meaning beyond stating 'one pack' to reinforce that pack_id is singular. The schema already lists examples. Baseline 3 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 action ('Returns') and the resource ('detailed metadata, coverage, freshness, preferred canonical tool guidance, and first-query examples for one pack'). It distinguishes from siblings like get_catalog (which lists packs) and query_dataset (which queries data).

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 'Call this before querying a new pack' and provides rationale ('so you can see time shape, coverage limits, and the paste-ready first query'). It does not explicitly mention when not to use it or name alternatives, but the guidance is clear.

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

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

Annotations provide readOnlyHint=true, but description adds critical paywall behavior (HTTP 402 flow) and region filter constraints. Does not mention rate limits or failure modes beyond payment.

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 covering purpose, best use, region IDs, and payment flow. No fluff, efficient structure, and all sentences add 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?

Covers purpose, usage, payment, and region filters. However, lacks description of output schema or return format, which is important for a tool with no output schema and nested parameters.

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

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

Schema coverage is 100% (baseline 3). Description adds value by specifying metric examples ('event_count', 'max_water_height_m') and providing guidance on limit usage with time ranges or region_ids.

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 'tsunamis_events for historical tsunami records and wave-height metrics' and specifies best uses such as event counts and max water height. It distinguishes itself from sibling earthquake/volcano tools by domain.

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 usage context: best for specific queries, region filter IDs (ISO3, ocean-region), and explicit payment flow ('call without payment first'). Missing explicit when-not-to-use but domain differentiation serves.

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 aligns with the readOnlyHint annotation by stating 'queries' and 'historical', so no contradiction. It adds useful context about year-style time filters but does not disclose other behaviors like pagination or rate limits. Annotations already provide safety, so a score of 3 is appropriate.

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, front-loaded with purpose, no redundant or extraneous information. 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?

Covers data source, typical use, and filter hints. However, lacking an output schema, the description could elaborate on the return structure (e.g., list of events with metrics) to be fully complete. Still, given schema coverage and annotations, it is mostly adequate.

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 each parameter. The description adds minor extra context about year-style time filters for the 'filters' parameter, but does not significantly enhance understanding of other parameters. Baseline is 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?

Description clearly states the tool queries 'volcanoes_events' for historical eruption records and metrics, with specific use cases like eruption counts, VEI thresholds, and top-event lookups. It implicitly distinguishes from the sibling 'get_live_volcano_events' by focusing on historical data.

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 (historical queries, eruption counts) and filter formatting (year-style time filters). Does not explicitly exclude sibling tools but implies using 'get_live_volcano_events' for live data. Could improve by stating alternatives outright.

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 noting it's a 'Free geography utility' with 'No payment required.' No contradiction, and no missing behavioral traits like rate limits or error handling are critical for this simple read tool.

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

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

Three concise sentences front-loaded with purpose, usage, and free status. No fluff 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?

With no output schema, the description adequately describes the return value (parent, ancestors, children by level). Sufficient for a simple read-only tool with only one required parameter.

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 description adds minimal extra meaning—only the example 'USA-CA-037' which is already in 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?

The description clearly states the verb 'returns' and resource 'administrative hierarchy', specifying parent, ancestors, and children. It distinguishes from sibling tools like loc_id_info and get_boundary by focusing on hierarchy traversal.

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 a clear use case: 'walk up or down the loc_id spine and clip to any administrative level.' However, it does not explicitly mention when not to use or alternatives, though sibling names are available for context.

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

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

Annotations already declare readOnlyHint=true, so the description's mention of 'Free geography utility' adds context about cost. It also lists the exact fields returned, which is transparent. No contradictions 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 two concise sentences: first states purpose and outputs, second notes no payment. Every sentence adds value without 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 tool with 2 parameters, no output schema, and read-only annotations, the description fully explains what the tool does and returns. No gaps remain.

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 has 100% coverage with descriptions for both parameters (loc_id with example, request_id as tracing). The description does not add new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('returns') and resource ('descriptive metadata for a DaedalMap loc_id'), listing specific fields (name, admin level, parent, centroid, bounding box, child counts). It distinguishes from siblings like 'loc_id_hierarchy' and 'get_boundary' by focusing on metadata rather than hierarchy or geometry.

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

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

The description says 'Free geography utility' and 'No payment required,' implying it's a general-purpose tool, but it does not explicitly state when to use this tool over alternatives like 'loc_id_hierarchy' or 'resolve_point'. Usage context is implied but not guided.

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

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

Annotations indicate readOnlyHint=true, and the description confirms it is a query, with no contradiction. The description adds behavioral context by listing free versus paid packs, implying access restrictions beyond the read-only nature.

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 first sentence defines the tool's purpose and contract, the second lists packs. It is front-loaded and efficient.

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 8 parameters (all optional, nested objects) and no output schema, the description provides a good high-level overview. It lists all available packs, which is crucial for the agent. However, it lacks details on output structure or how to use filters/metrics, though schema covers these.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add any parameter-specific information beyond what the schema provides; it only mentions source_id and pack_id generically.

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 generic structured query for direct source_id or pack_id access, listing both free and paid packs. This distinguishes it from sibling tools that target specific resources like get_earthquake_events 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 implicitly tells when to use it (for source_id or pack_id access, for listed packs) but does not explicitly exclude sibling tools or provide alternatives. The mention of free versus paid packs adds contextual 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. Description adds that it is free and no payment required, which is useful cost context. However, it does not disclose potential errors, rate limits, or behavior for points outside 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?

Two sentences that efficiently communicate purpose, output, and cost. Could be slightly more structured but no wasted 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?

No output schema, but description adequately describes return fields: country, deepest loc_id, admin stack. Missing error handling, but overall sufficient for a straightforward geocoding 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 clear descriptions for lat, lon, request_id. The description adds no new detail about the parameters beyond their role in conversion. 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 does reverse geocoding: converts lat/lon to DaedalMap loc_id administrative chain. It distinguishes itself from siblings like get_boundary or loc_id_hierarchy by specifying it converts raw coordinates to loc_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?

Explicitly mentions use case: joining spatial data to the loc_id spine used by data packs. Does not explicitly state when not to use or list alternatives, but context is clear.

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

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

Annotations already indicate readOnlyHint=true, and the description adds minimal behavioral context (e.g., 'published', 'discovery helper') but does not detail result format or any other behavioral traits 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?

Two concise sentences that front-load the action, with no wasted words or repetitive information.

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

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

Given no output schema and 7 optional parameters, the description is somewhat complete but lacks explanation of the output format or how parameters interact, which could confuse an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description groups parameters conceptually (event-type direction, year window) but does not add new meaning beyond the schema's own 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 it searches cross-disaster link families by event-type direction and optional filters, which distinguishes it from siblings like get_disaster_links_for_event by emphasizing discovery before having an exact event 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?

The description explicitly says 'Use this when you want to discover whether a relationship family exists before you have an exact event id,' providing clear context for when to use it, though it does not name alternatives explicitly.

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