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

TableJSON 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

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.

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 readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds real behavioral context: the 25000-row cap, that one batch uses a single from/to/crosswalk route, that an exact miss ends on that artifact, that ambiguity surfaces a typed error listing valid crosswalk_ids, and that authored allowances/payment policy may apply. It stops short of describing result ranking or truncation behavior, keeping it at a strong 4 rather than 5.

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?

The scope constraint and required fields are front-loaded, and nearly every sentence carries routing or constraint information. It is dense and slightly jargon-heavy (loc_id universe, typed ambiguity error), which costs a point against a perfectly economical definition, but little is wasted.

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-capable conversion tool with an output schema already documenting returns, the description covers scope, batching, routing, error behavior, and access policy well. The only soft spot is the external reference to 'tools/list access metadata' for allowances, which assumes knowledge the agent may not have in-context.

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 description coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining the call-level constraints tying parameters together (one from_system, one to_system, one crosswalk_id per batch; per-item limit multiplied by item count capped at 25000) and by clarifying crosswalk_id's origin in the ambiguity error.

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 (convert) and resource (geographic references) along with the scope unit (one ISO3/GLOBAL/MARINE per call) and the route (from_system -> loc_id -> to_system). It clearly differentiates itself from siblings by naming get_geography for family/scope discovery and by distinguishing itself from lookup tools via the crosswalk/batch framing.

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 explicit routing rules: omit to_system to enter the loc_id universe, use from_system admin_boundary with country_hint for admin or city names, and use get_geography when family or scope coverage is unknown. It also names the alternative tool and the condition that selects it, which is exactly the when/when-not guidance missing from most definitions.

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.