daedal-map

Overview Schema Source Related Servers Discussions Admin

Convert Geographic Reference

convert_reference

Read-onlyIdempotent

Convert geographic identifiers or names between reference systems within one declared country, global, or marine scope using loc_id or a published crosswalk for reliable joins.

Instructions

Convert within one declared scope per call: iso3 is required and names one ISO3 country, GLOBAL, or MARINE. A batch uses one from_system, to_system, and crosswalk_id, with at most 25000 requested result rows. Convert X -> loc_id -> Y; omit to_system to enter the loc_id universe. For admin or city names use from_system admin_boundary with a country_hint inside the declared country. A published direct crosswalk uses one selected artifact; if the system pair has multiple artifacts, supply crosswalk_id from the typed ambiguity error. An exact miss ends on that artifact. Use get_geography when family or scope coverage is unknown. The tools/list access metadata states authored free, account, and paid item allowances; active operator policy may waive payment.

Input Schema

Name	Required	Description	Default
`iso3`	No	Required scope pack for the entire call: one ISO3 country, GLOBAL, or MARINE. Every item must stay within this scope.
`as_of`	No	ISO date or year used for time-bounded identities.
`items`	No	Reference conversions within one scope and one source/target/crosswalk route. Split mixed routes. Maximum requested item count times per-item limit is 25000.
`limit`	No	Maximum ranked output references to return. Default 10.
`value`	No	Identifier or name in the input system, for example 'Springfield, Illinois' with admin_boundary.
`batch_id`	No	Optional caller-supplied batch id for tracing.
`min_share`	No	Optional minimum overlap share threshold.
`to_system`	No	Optional output reference system. Defaults to DaedalMap loc_id; provide zcta, nws_fire, overlay_nws_public_zone, overlay_tribal, admin_local, or another catalog system for any-to-any conversion.	daedalmap.loc_id
`request_id`	No	Optional caller-supplied request id for tracing.
`from_system`	No	Input reference system, such as admin_boundary (admin and city names; admin_text and place_name are accepted aliases), zip, overlay_zcta, nws_fire, tribal, or loc_id.
`country_hint`	No	Optional country hint for admin/name resolution (USA), or a subdivision to search within (USA-OR). Names may also carry their parent: 'Washington County, Oregon'. Ambiguous names return candidates instead of a match.
`crosswalk_id`	No	Exact published crosswalk ID when the source/target system pair has multiple artifacts. A route ambiguity error lists valid IDs.
`admin_level_hint`	No	Optional admin-level hint for admin/name resolution.
`target_admin_level`	No	Admin level used as the intermediate crosswalk target. Default admin_2.
`relationship_vintage`	No	Optional source relationship vintage to require.

Output Schema

Name	Required	Description	Default
`ok`	No
`from`	No
`error`	No
`loc_id`	No
`reason`	No
`results`	No
`batch_id`	No
`guidance`	No
`warnings`	No
`next_step`	No
`to_system`	No
`item_count`	No
`request_id`	No
`from_system`	No
`clarification`	No
`meter_receipt`	No
`converted_count`	No
`unconverted_count`	No
`settlement_receipt`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv1.0.3Nov 12, 2026

changedInput schema / anyOf

Previous value: -[
-  {
-    "required": [
-      "from_system",
-      "value"
-    ]
-  },
-  {
-    "required": [
-      "items"
-    ]
-  }
-]New value: +[
+  {
+    "required": [
+      "iso3",
+      "from_system",
+      "value"
+    ]
+  },
+  {
+    "required": [
+      "iso3",
+      "items"
+    ]
+  }
+]

changedInput schema / properties / country_hint / description

Previous value: -"Optional country hint for admin/name resolution."New value: +"Optional country hint for admin/name resolution (USA), or a subdivision to search within (USA-OR). Names may also carry their parent: 'Washington County, Oregon'. Ambiguous names return candidates instead of a match."

addedInput schema / properties / crosswalk_id

Added value: +{
+  "description": "Exact published crosswalk ID when the source/target system pair has multiple artifacts. A route ambiguity error lists valid IDs.",
+  "type": "string"
+}

changedInput schema / properties / from_system / description

Previous value: -"Input reference system, such as zip, overlay_zcta, nws_fire, tribal, admin_boundary, or loc_id."New value: +"Input reference system, such as admin_boundary (admin and city names; admin_text and place_name are accepted aliases), zip, overlay_zcta, nws_fire, tribal, or loc_id."

changedInput schema / properties / iso3 / description

Previous value: -"Country hint for crosswalk artifacts. Default USA."New value: +"Required scope pack for the entire call: one ISO3 country, GLOBAL, or MARINE. Every item must stay within this scope."

addedInput schema / properties / iso3 / minLength
```
Added value: +3
```

changedInput schema / properties / items / description

Previous value: -"Reference conversions to run in one call. Default public cap is deployment-configurable."New value: +"Reference conversions within one scope and one source/target/crosswalk route. Split mixed routes. Maximum requested item count times per-item limit is 25000."

changedInput schema / properties / items / items / properties / country_hint / description

Previous value: -"Optional country hint for admin/name resolution."New value: +"Optional country hint for admin/name resolution (USA), or a subdivision to search within (USA-OR). Names may also carry their parent: 'Washington County, Oregon'. Ambiguous names return candidates instead of a match."

addedInput schema / properties / items / items / properties / crosswalk_id

Added value: +{
+  "description": "Exact published crosswalk ID when the source/target system pair has multiple artifacts.",
+  "type": "string"
+}

changedInput schema / properties / items / items / properties / iso3 / description

Previous value: -"Optional country hint for this row."New value: +"Optional repeat of the top-level scope; must match it. Split mixed countries or packs into separate calls."

changedInput schema / properties / value / description

Previous value: -"Identifier or name in the input system."New value: +"Identifier or name in the input system, for example 'Springfield, Illinois' with admin_boundary."

Changed1 schema field changedv1.0.1Sep 24, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": true,
+  "anyOf": [
+    {
+      "required": [
+        "ok",
+        "results"
+      ]
+    },
+    {
+      "required": [
+        "item_count",
+        "results"
+      ]
+    },
+    {
+      "required": [
+        "error"
+      ]
+    }
+  ],
+  "properties": {
+    "batch_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "clarification": {
+      "type": "object"
+    },
+    "converted_count": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "error": {
+      "additionalProperties": true,
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "details": {
+          "type": "object"
+        },
+        "message": {
+          "type": "string"
+        },
+        "retry_hint": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "type": "object"
+    },
+    "from": {
+      "type": "object"
+    },
+    "from_system": {
+      "type": "string"
+    },
+    "guidance": {
+      "type": "object"
+    },
+    "item_count": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "loc_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "meter_receipt": {
+      "type": "object"
+    },
+    "next_step": {
+      "additionalProperties": true,
+      "anyOf": [
+        {
+          "required": [
+            "action"
+          ]
+        },
+        {
+          "required": [
+            "tool"
+          ]
+        }
+      ],
+      "properties": {
+        "action": {
+          "type": "string"
+        },
+        "arguments": {
+          "type": "object"
+        },
+        "tool": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "request_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "results": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "error": {
+            "additionalProperties": true,
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "details": {
+                "type": "object"
+              },
+              "message": {
+                "type": "string"
+              },
+              "retry_hint": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "message"
+            ],
+            "type": "object"
+          },
+          "id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          },
+          "ok": {
+            "type": "boolean"
+          },
+          "row_index": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "settlement_receipt": {
+      "type": "object"
+    },
+    "to_system": {
+      "type": "string"
+    },
+    "unconverted_count": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "warnings": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

AddedSep 24, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description is free to add operational context — the 25000 requested-row ceiling, the single-scope/single-route constraint, exact-miss termination on an artifact, and ambiguity errors returning candidate crosswalk IDs. The closing note about tools/list access metadata and operator payment policy adds unusual but relevant transparency, though it is vague enough to be only marginally actionable.

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

Conciseness4/5

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

Front-loaded with the scope constraint and tightly written; nearly every clause carries a rule the agent needs. It is telegraphic to the point that phrases like 'within one declared scope' and 'An exact miss ends on that artifact' take a re-read, and the pricing sentence is tangential to invocation.

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

Completeness4/5

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

For a 15-parameter batch tool with a published output schema, the description covers scope rules, route selection, ambiguity handling, batch limits, and name-resolution hints — enough to call correctly. Remaining gaps (per-item limit interaction, as_of/vintage semantics) are largely handled by the schema descriptions.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: iso3 is a scope pack (ISO3, GLOBAL, or MARINE) that every item must stay within, batches share one from_system/to_system/crosswalk_id, and omitting to_system selects the loc_id universe rather than a default conversion. That exceeds what the per-field schema text alone conveys.

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

Purpose5/5

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

States a specific verb and resource — 'Convert' a geographic reference between named systems — and immediately bounds it to 'one declared scope per call'. It also names the pivot ('Convert X -> loc_id -> Y') and explicitly routes scope/family discovery to get_geography, so an agent can separate it from catalog and lookup siblings.

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

Usage Guidelines5/5

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

Gives concrete when-to-use rules: omit to_system to enter the loc_id universe, use from_system admin_boundary with country_hint for admin or city names, supply crosswalk_id from the typed ambiguity error when a system pair has multiple artifacts, and fall back to get_geography when family or scope coverage is unknown. It also states exclusions implicitly by requiring one scope and one route per call.

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

Deploy Server