DaedalMap Reverse Geocoding (coordinates to loc_id)

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description's only behavioral addition is that the response carries a catalog download URL, which is already implied by the output schema; the long paragraph about worldwide coverage and per-country releases is scope marketing rather than behavioral disclosure.

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 actionable content (what it lists, the download URL, the get_pack/get_geography routing) is front-loaded, but it is then buried under a lengthy 'Current catalog' paragraph listing 252 entities and eight countries that does nothing for tool selection or invocation.

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 annotations covering safety and an output schema covering returns, the description only needs to explain the selector and routing, which it mostly does. However, the undefined 'scope IDs' terminology and the routing to a non-sibling tool leave small gaps for an agent deciding between catalog and pack calls.

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

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

Schema coverage is 100% and the enum values are self-explanatory, so the baseline is 3. The description goes beyond this by mapping each enum value to a distinct return shape ('data' yields pack IDs, 'geometry' yields family and scope IDs), which genuinely adds meaning 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?

It names a specific verb ('list') and resource ('published pack IDs or family and scope IDs') and ties the output to the required catalog selector. It is distinguishable from the generic get_data/get_pack siblings, though the phrase 'family and scope IDs' is jargon that is never defined.

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

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

It gives explicit routing: 'Use get_pack for data or get_geography for geometry,' which tells the agent when to pick this tool over an alternative. The weakness is that get_geography is not among the listed siblings, so the routing target is ambiguous for the agent.

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

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

Annotations already cover readOnly, idempotent, closed-world and non-destructive behavior, so the bar is lower. The description still adds real context: results come from catalog metadata only, the optional year resolves to the latest admitted edition no later than that year, and a missing edition index is reported explicitly rather than silently ignored.

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 tight sentences with no filler, and the core operation is front-loaded before the year-selection detail. The phrasing is jargon-dense but each sentence carries 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 an output schema present, return values need no further explanation, and the annotations cover the safety profile. The description covers the operation and the year behavior adequately; the only real gap is not clarifying the family_id/scope_id distinction and their mutual exclusivity.

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 0%, so the description carries the burden for three parameters. It explains 'year' semantics well (latest admitted edition no later than the year, with explicit reporting when no index exists), but says nothing about the meaning of family_id vs scope_id or the oneOf exclusivity rule that requires exactly one of them.

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 names a specific verb ('Inspect') and resource ('one published geometry family across scopes or one scope across families'), which distinguishes it from siblings like compare_geographies, get_shape, and get_data. It is clear what the tool returns, though the family-vs-scope duality is stated rather densely and its relationship to sibling tools is not explicitly contrasted.

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 'from catalog metadata only' implicitly signals this is a metadata lookup rather than a data/geometry fetch (vs get_data, get_shape), which gives an agent some routing signal. However, there is no explicit when-to-use, when-not-to-use, or named alternative sibling, so usage must be inferred.

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 idempotentHint=true, covering the safety profile. The description adds a bit of behavioral context by mentioning 'exact contract' and 'bounded workflow overview', but it does not disclose potential error conditions or response formats. This is acceptable given the annotations, so a 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?

The description is a single, well-structured sentence that efficiently presents both modes without redundancy. Every phrase adds value, and it is front-loaded with the primary action.

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

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

The description is adequate but relies heavily on the schema for constraints (e.g., oneOf logic, enum values, mutual exclusivity). It does not mention optional parameters or edge cases, but given the rich schema and annotations, it covers the essential purpose. A 3 reflects that it is sufficient but not exhaustive.

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% and each parameter already has a thorough description (e.g., 'Do not combine with tool_name'). The tool description adds no extra parameter detail beyond the schema, 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 purpose: describe a tool (with its exact contract) or return a workflow overview for a supported topic. It uses specific verbs and resources, and the two modes are distinct. This differentiates it from sibling data-fetching tools like get_data and 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 implies when to use each mode by stating the two options, and the schema enforces mutual exclusivity. However, it does not explicitly name alternatives or state when NOT to use this tool (e.g., for actual data retrieval). Still, the purpose is clear enough for an agent to infer correct usage.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description still adds real behavioral context by disclosing that results come back as a best overlap plus nearby matches at each level with share-of-viewport and share-of-loc_id figures, and by warning that oversized views may need zooming. It does not say what happens to matches outside the viewport or how partial overlaps are ranked, leaving the ranking behavior opaque.

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 opening sentences front-load the comparison and the required input efficiently, and the return-shape sentence is informative. The closing line, 'This tool reads no country deep bank,' is unexplained internal jargon that costs space without giving the agent an actionable rule, and 'Large views may require zooming in' is too vague to guide a retry strategy.

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 full schema coverage, an output schema, and complete annotations, most of the burden is carried elsewhere, and the description fills in the comparison target and the resolution limits. The notable gap is sibling routing against resolve_deep_bbox and resolve_point, which matters given three similar-sounding resolve tools. Otherwise an agent has enough to call this 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 coverage is 100%, so both corners and request_id are already documented, including the four-distinct-corners and antimeridian constraints. The description mirrors that with 'Supply its four corners' and 'non-wrapping' but adds no format, ordering, or tolerance detail beyond the schema. Baseline 3 is appropriate when the schema carries this much weight.

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 gives a specific verb and resource: compare one non-wrapping rectangular WGS84 viewport against the Global administrative spine through Admin 2, and return best equal-area overlap plus nearby matches. That is far more than a restatement of the name. It stops short of naming a sibling such as resolve_deep_bbox or resolve_point, so the agent must infer the split from the domain wording alone.

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

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

Usage is implied by the constraints: supply four corners, views must not cross the antimeridian, and large views may need zooming in. There is no explicit guidance on when to pick this over resolve_deep_bbox or resolve_point, which is the main routing decision an agent faces here. The closing line about the 'country deep bank' gestures at a boundary but does not state a rule the agent can act on.

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 readOnly, idempotent, non-destructive and closed-world behavior, so the bar is lower; the description still adds genuine behavior beyond them by explaining the internal routing to one country-specific partition and disclosing a real failure mode ('broad views may require zooming in'). It does not describe cost, latency, or what happens when the rectangle straddles partitions, but the output schema covers return shape.

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 tight sentences with the routing behavior front-loaded and the input requirement and caveat following — no filler. The density of unexplained internal jargon ('Admin 1-6 spine', 'Admin 1-owned exact partition') costs a point because an unfamiliar agent must decode terms that are never defined.

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, idempotent resolver with a full input schema and an output schema, the definition covers purpose, precondition, input provenance, and one operational caveat, which is close to sufficient. It is only short of a plain statement of the result (what the deep partition comparison yields) and of how it relates to its named siblings.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds two constraints not in the schema: the corners must be the 'original' four (i.e., not narrowed from the shallow call) and they are WGS84, which the schema never states. It adds nothing about request_id, which is fine since the schema documents it as an optional tracing 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 names a specific operation (a second-pass rectangle overlap resolved against a single shallow administrative loc_id) and explicitly frames it as the deep counterpart to a first shallow pass, which distinguishes it from resolve_bbox and resolve_deep_point. The wording is domain-dense ('Admin 1-owned exact partition', 'Admin 1-6 spine'), so an agent gets the shape of the operation but not a plain-language statement of what it returns.

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?

'Second-pass' and 'within one returned shallow administrative loc_id' establish that this tool must be called after a shallow lookup and scoped to one of its results, which is real sequencing guidance. However, the prerequisite sibling (resolve_bbox) is never named, and there is no explicit statement of when to skip the deep pass or what to do if the shallow result is absent — the agent must infer the call order.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds real behavioral context: the single/bulk requests share the same scoped contract, family defaults to administrative, and shape-backed families bypass crosswalks for a direct bbox-to-exact-shape lookup.

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 critical precondition is front-loaded in the first sentence, which is good. However, the trailing "Current catalog" paragraph about 252 entities and country releases is long shared boilerplate that does not help an agent invoke this tool correctly and dilutes the signal.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the upstream dependency, family default, and bulk contract, leaving little an agent needs that is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the shallow_loc_id must be one shared value returned by resolve_point, family defaults to administrative, and the points array must already fall within the shallow scope. Only target_admin_level is left to 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?

States a specific action (second-pass containment resolution) and its required inputs, and explicitly distinguishes itself from the sibling resolve_point by positioning as the follow-up pass. An agent can tell what this does and how it differs from the shallow pass without opening either schema.

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?

"Second-pass containment only after resolve_point" is an explicit precondition and names the required upstream call, and it points to get_catalog(catalog='geometry') for valid family values. It does not spell out negative cases (e.g., when to skip a deep pass), so it falls just short of full when/when-not coverage.

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 readOnly/idempotent/non-destructive, so the description is free to add routing behavior, which it does well: 'No call crosses scopes or opens another family's bank' and the marine_jurisdiction exclusion are non-obvious constraints an agent could not infer from schema. It does not describe batching behavior or result shape, but the output schema covers returns.

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 routing rules are front-loaded and dense with value, but the trailing catalog paragraph ('252 geographic entities... Australia, Brazil, Canada...') is long, reads as release-note copy, and could be condensed to one sentence about deeper tiers being available in select countries.

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 a full schema, rich annotations, and an output schema, the only missing piece is coverage depth, and the description addresses it via the catalog paragraph. An agent has enough to route a point correctly across GLOBAL/ISO3/MARINE; the only gap is not naming resolve_deep_point for deeper queries.

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 goes further by explaining the conditional relationship between scope_id, family, and water_kind (e.g., water_body requires named or zone), which is semantics the enum alone does not convey. The lat/lon vs points alternation is left to the schema's oneOf.

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

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

States a specific verb and resource: 'Resolve WGS84 coordinates in exactly one selected scope and family,' and enumerates the scope families it handles. An agent can tell it apart from get_geography and compare_geographies, though the sibling resolve_deep_point (the obvious alternative for deeper tiers) is only implicitly gestured at via 'reaching up to Admin 2.'

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

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

Gives explicit per-scope conditions: GLOBAL finds Admin0, ISO3 finds the shallow country bank, MARINE requires one jurisdiction family or water_body with water_kind, and marine_jurisdiction has no point route. It also points to get_catalog for family discovery. It stops short of naming resolve_deep_point as the tool to use when the shallow bank is insufficient.

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