daedal-map

Overview Schema Source Related Servers Discussions Admin

Convert Geographic Reference

convert_reference

Read-onlyIdempotent

Convert geographic references between systems, such as ZIP codes to loc_id or any-to-any formats. Supports single or batch inputs with optional country and time filters.

Instructions

The single geographic reference converter. Converts one reference, or a bounded list, through DaedalMap loc_id: X -> loc_id -> Y. Omit to_system to enter the loc_id universe; provide it for any-to-any conversion. Use get_pack first when the family or country-specific system is unknown. No payment required.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`iso3`	No	Country hint for crosswalk artifacts. Default USA.
`as_of`	No	ISO date or year used for time-bounded identities.
`items`	No	Reference conversions to run in one call. Default public cap is deployment-configurable.
`limit`	No	Maximum ranked output references to return. Default 10.
`value`	No	Identifier or name in the input system.
`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 zip, overlay_zcta, nws_fire, tribal, admin_boundary, or loc_id.
`country_hint`	No	Optional country hint for admin/name resolution.
`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

TableJSON 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.

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.7/5.0

Behavior4/5

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

Annotations already declare readOnly=true, idempotent=true, and destructive=false, so the safety profile is covered. The description adds useful context beyond annotations: the loc_id intermediate path, the bounded-list capability, and that no payment is required.

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

Conciseness5/5

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

Four short sentences cover what the tool does, how conversion works, the key to_system decision, a routing alternative, and a payment caveat. Every sentence earns its place and the core function is front-loaded.

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

Completeness5/5

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

Given the rich output schema, 100% parameter descriptions, and strong annotations, the description provides the missing operational context: the intermediate loc_id step, the get_pack precondition, and the no-payment note. Nothing essential for correct invocation is missing.

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 the baseline is 3. The description adds meaningful conceptual semantics by clarifying that conversions route through DaedalMap loc_id and that omitting to_system keeps you in the loc_id universe, which the schema alone does not state as directly.

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?

The description names a specific verb and resource ('Converts one reference, or a bounded list') and explains the conversion path 'X -> loc_id -> Y'. Calling itself 'The single geographic reference converter' helps distinguish it from sibling tools like get_pack and resolve_point.

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?

It gives explicit mode guidance: 'Omit to_system to enter the loc_id universe; provide it for any-to-any conversion.' It also names an alternative and its trigger condition: 'Use get_pack first when the family or country-specific system is unknown.'

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

Deploy Server