DaedalMap Geography Tools (loc_id)

Convert Geographic Reference

convert_reference

Read-onlyIdempotent

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.

Changed7 schema fields changedOct 15, 2026

changedInput schema / anyOf

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

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

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

Changed4 schema fields changedOct 11, 2026

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

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

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 changedSep 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"
+}

Changed9 schema fields changedSep 21, 2026

changedInput schema / anyOf

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

addedInput schema / properties / admin_level_hint

Added value: +{
+  "description": "Optional admin-level hint for admin/name resolution.",
+  "maximum": 6,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / as_of

Added value: +{
+  "description": "ISO date or year used for time-bounded identities.",
+  "type": "string"
+}

addedInput schema / properties / country_hint

Added value: +{
+  "description": "Optional country hint for admin/name resolution.",
+  "type": "string"
+}

addedInput schema / properties / items / items / properties / admin_level_hint

Added value: +{
+  "description": "Optional admin-level hint for admin/name resolution.",
+  "maximum": 6,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / items / items / properties / as_of

Added value: +{
+  "description": "ISO date or year used for time-bounded identities.",
+  "type": "string"
+}

addedInput schema / properties / items / items / properties / country_hint

Added value: +{
+  "description": "Optional country hint for admin/name resolution.",
+  "type": "string"
+}

addedInput schema / properties / to_system / default
```
Added value: +"daedalmap.loc_id"
```

changedInput schema / properties / to_system / description

Previous value: -"Output reference system, such as loc_id, zcta, nws_fire, overlay_nws_public_zone, overlay_tribal, admin_local, or admin_geometry."New value: +"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."

Changed6 schema fields changedAug 26, 2026

removedInput schema / properties / bridge_vintage

Removed value: -{
-  "description": "Optional source bridge vintage to require.",
-  "type": "string"
-}

changedInput schema / properties / iso3 / description

Previous value: -"Country hint for bridge artifacts. Default USA."New value: +"Country hint for crosswalk artifacts. Default USA."

removedInput schema / properties / items / items / properties / bridge_vintage

Removed value: -{
-  "description": "Optional bridge vintage for this row.",
-  "type": "string"
-}

addedInput schema / properties / items / items / properties / relationship_vintage

Added value: +{
+  "description": "Optional relationship vintage for this row.",
+  "type": "string"
+}

addedInput schema / properties / relationship_vintage

Added value: +{
+  "description": "Optional source relationship vintage to require.",
+  "type": "string"
+}

changedInput schema / properties / target_admin_level / description

Previous value: -"Admin level used as the intermediate bridge target. Default admin_2."New value: +"Admin level used as the intermediate crosswalk target. Default admin_2."

Changed4 schema fields changedAug 8, 2026

addedInput schema / anyOf

Added value: +[
+  {
+    "required": [
+      "from_system",
+      "value",
+      "to_system"
+    ]
+  },
+  {
+    "required": [
+      "items"
+    ]
+  }
+]

addedInput schema / properties / batch_id

Added value: +{
+  "description": "Optional caller-supplied batch id for tracing.",
+  "type": "string"
+}

addedInput schema / properties / items

Added value: +{
+  "description": "Reference conversions to run in one call. Default public cap is deployment-configurable.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "bridge_vintage": {
+        "description": "Optional bridge vintage for this row.",
+        "type": "string"
+      },
+      "from_system": {
+        "description": "Input reference system for this row. Defaults to top-level from_system when omitted.",
+        "type": "string"
+      },
+      "id": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "string"
+          }
+        ],
+        "description": "Optional caller identifier echoed in the result."
+      },
+      "iso3": {
+        "description": "Optional country hint for this row.",
+        "type": "string"
+      },
+      "limit": {
+        "description": "Maximum ranked output references for this row.",
+        "maximum": 100,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "min_share": {
+        "description": "Optional minimum overlap share threshold for this row.",
+        "maximum": 1,
+        "minimum": 0,
+        "type": "number"
+      },
+      "row_index": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "string"
+          }
+        ],
+        "description": "Optional caller row identifier echoed in the result."
+      },
+      "target_admin_level": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "integer"
+          }
+        ],
+        "description": "Optional intermediate admin target level for this row."
+      },
+      "to_system": {
+        "description": "Output reference system for this row. Defaults to top-level to_system when omitted.",
+        "type": "string"
+      },
+      "value": {
+        "description": "Identifier or name in the input system.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "value"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

removedInput schema / required

Removed value: -[
-  "from_system",
-  "value",
-  "to_system"
-]

AddedAug 3, 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.

All DaedalMap Geography Tools (loc_id) tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.