EasyTerritory MCP

Merge Territories

territory_merge

Destructive

Merges a pair of adjacent territories and rebalances the rest of the alignment with minimal disruption (N to N-1 territories), e.g. when a rep leaves and the neighbors absorb the territory. territory_id_b is the territory that goes away; territory_id_a is an adjacent neighbor that keeps its id. The same job rebalances every remaining territory. One call removes one territory; non-adjacent ids return NON_ADJACENT_TERRITORIES. Needs source_tal_id and the Territory Solution from map_session_id or ts_handle; workload balance needs dwell_time (CLARIFICATION_REQUIRED otherwise). Writes a new derived alignment. Returns a task.

Input Schema

Name	Required	Description	Default
`objective`	No
`ts_handle`	No	Territory Solution reference (tsh_...) from a build, ingest_accounts, import_geojson, import_designer_project, or get_map_visualization; Territory Solutions are not accepted inline.
`dwell_time`	No
`part_layer`	No	Part layer (e.g. us_zips). Required only when not inferable from the source TAL.
`point_layer`	No	Optional point layer used to compute per-part workload/metric measures. When omitted, a uniform geography-only weighting is used.
`new_tal_label`	No	Label for the derived TAL. Defaults to '<source label> (<operation>)'.
`repair_policy`	No	Topology repair for dissolved territories. default fills interior holes in the dissolved geometry (no part is added or reassigned; repair_summary.changed_part_ids lists the territories' own parts). report_only detects holes and changes nothing (warning REPAIR_AVAILABLE). strict fails with REPAIR_REQUIRED when a hole is found.	default
`source_tal_id`	No	Source TAL. Optional for form-capable clients that can answer via elicitation.
`map_session_id`	No	Open map session (msess_...) from get_map_visualization. Its Territory Solution is the input; omit ts_handle when set.
`territory_id_a`	No	First territory (id or label). The merged territory keeps this identity.
`territory_id_b`	No	Second territory (id or label). Must be adjacent to territory_id_a.
`balance_tolerance`	No	Accepted for compatibility. The power-diagram rebalance converges on its own internal tolerance, so this value no longer gates per-part moves.
`disruption_weight`	No	Incumbency stickiness for the warm-started power-diagram rebalance. 0 is a pure power re-solve (max balance, more churn); higher values keep more of the source alignment by requiring a neighbor territory to inflate further before it can claim a border part.
`visit_frequency_field`	No	Numeric visits-per-cycle column on the point layer. When omitted, inherits from source TAL build_provenance or point-layer metadata.

Output Schema

Name	Required	Description
`ok`	Yes
`error`	No	Present when ok is false.
`result`	No	Present when ok is true. A submission returns the task reference (task_id, next_action, sleep_ms); the completed task result carries the remaining fields.
`warnings`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedNov 1, 2026

addedInput schema / properties / balance_tolerance / description

Added value: +"Accepted for compatibility. The power-diagram rebalance converges on its own internal tolerance, so this value no longer gates per-part moves."

addedInput schema / properties / disruption_weight / description

Added value: +"Incumbency stickiness for the warm-started power-diagram rebalance. 0 is a pure power re-solve (max balance, more churn); higher values keep more of the source alignment by requiring a neighbor territory to inflate further before it can claim a border part."

addedInput schema / properties / map_session_id / description

Added value: +"Open map session (msess_...) from get_map_visualization. Its Territory Solution is the input; omit ts_handle when set."

addedInput schema / properties / new_tal_label / description

Added value: +"Label for the derived TAL. Defaults to '<source label> (<operation>)'."

addedInput schema / properties / part_layer / description

Added value: +"Part layer (e.g. us_zips). Required only when not inferable from the source TAL."

addedInput schema / properties / point_layer / description

Added value: +"Optional point layer used to compute per-part workload/metric measures. When omitted, a uniform geography-only weighting is used."

addedInput schema / properties / source_tal_id / description

Added value: +"Source TAL. Optional for form-capable clients that can answer via elicitation."

addedInput schema / properties / territory_id_a / description

Added value: +"First territory (id or label). The merged territory keeps this identity."

addedInput schema / properties / territory_id_b / description

Added value: +"Second territory (id or label). Must be adjacent to territory_id_a."

removedInput schema / properties / ts

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Ts"
-}

addedInput schema / properties / ts_handle / description

Added value: +"Territory Solution reference (tsh_...) from a build, ingest_accounts, import_geojson, import_designer_project, or get_map_visualization; Territory Solutions are not accepted inline."

addedInput schema / properties / visit_frequency_field / description

Added value: +"Numeric visits-per-cycle column on the point layer. When omitted, inherits from source TAL build_provenance or point-layer metadata."

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / properties

Added value: +{
+  "error": {
+    "description": "Present when ok is false.",
+    "properties": {
+      "ask_user": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "code": {
+        "type": "string"
+      },
+      "details": {
+        "type": "object"
+      },
+      "do_this_next": {
+        "type": "object"
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "ok": {
+    "type": "boolean"
+  },
+  "result": {
+    "description": "Present when ok is true. A submission returns the task reference (task_id, next_action, sleep_ms); the completed task result carries the remaining fields.",
+    "properties": {
+      "balance_summary": {
+        "type": "object"
+      },
+      "disruption_summary": {
+        "type": "object"
+      },
+      "do_this_next": {
+        "type": "object"
+      },
+      "expires_at": {
+        "type": "string"
+      },
+      "job_id": {
+        "type": "string"
+      },
+      "next_action": {
+        "type": "string"
+      },
+      "operation": {
+        "type": "string"
+      },
+      "repair_summary": {
+        "type": "object"
+      },
+      "sleep_ms": {
+        "type": "integer"
+      },
+      "solver_diagnostics": {
+        "type": "object"
+      },
+      "source_tal_id": {
+        "type": "string"
+      },
+      "status": {
+        "type": "string"
+      },
+      "tal_id": {
+        "type": "string"
+      },
+      "task_id": {
+        "type": "string"
+      },
+      "terminal": {
+        "type": "boolean"
+      },
+      "territory_count": {
+        "type": "integer"
+      },
+      "ts_handle": {
+        "type": "string"
+      },
+      "ts_identity": {
+        "type": "object"
+      },
+      "ts_omitted": {
+        "type": "object"
+      }
+    },
+    "type": "object"
+  },
+  "warnings": {
+    "items": {
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  }
+}

addedOutput schema / required
```
Added value: +[
+  "ok"
+]
```

removedOutput schema / title

Removed value: -"territory_mergeDictOutput"

Changed1 schema field changedOct 20, 2026

changedInput schema / properties / objective / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "description": "Balance objective: {metric: '<column>|__account_count__', workload_bias: 0..100, metric_bias: 0..100}. Biases sum to 100. For pure metric balance, pass {metric: '<column>', workload_bias: 0, metric_bias: 100} (or {metric: '<column>'} on restructure tools). When omitted on restructure tools, inherits the source TAL build_provenance objective or seed_build target.",
+    "properties": {
+      "metric": {
+        "description": "Point metric column name to balance (e.g. 'Revenue', 'weekly_volume'), or '__account_count__' for location-count balance.",
+        "type": "string"
+      },
+      "metric_bias": {
+        "description": "Weight (0..100) on the metric or location-count dimension.",
+        "maximum": 100,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "workload_bias": {
+        "description": "Weight (0..100) on workload (drive time + dwell).",
+        "maximum": 100,
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedOct 14, 2026

changedInput schema / properties / dwell_time / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "description": "Onsite (dwell) time per visit: {type: 'scalar', value: <number>, unit: 'minutes'|'hours'} or {type: 'field', field: '<column>', unit: 'minutes'|'hours'}.",
+    "properties": {
+      "field": {
+        "description": "Point column name holding per-account onsite time when type='field'.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": {
+        "description": "Dwell source: 'scalar' for a fixed per-visit duration or 'field' for an ingested point column.",
+        "enum": [
+          "scalar",
+          "field"
+        ],
+        "type": "string"
+      },
+      "unit": {
+        "default": "minutes",
+        "description": "Time unit for value or field ('minutes' or 'hours').",
+        "enum": [
+          "minutes",
+          "hours"
+        ],
+        "type": "string"
+      },
+      "value": {
+        "description": "Confirmed onsite duration per visit when type='scalar'.",
+        "minimum": 0,
+        "type": "number"
+      }
+    },
+    "required": [
+      "type"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedOct 9, 2026

removedInput schema / properties / guidance_handle

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Guidance Handle"
-}

Changed2 schema fields changedOct 5, 2026

addedInput schema / properties / repair_policy / description

Added value: +"Topology repair for dissolved territories. default fills interior holes in the dissolved geometry (no part is added or reassigned; repair_summary.changed_part_ids lists the territories' own parts). report_only detects holes and changes nothing (warning REPAIR_AVAILABLE). strict fails with REPAIR_REQUIRED when a hole is found."

addedInput schema / properties / repair_policy / enum

Added value: +[
+  "default",
+  "strict",
+  "report_only"
+]

First observedSep 29, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Adds real context beyond the annotations: the call removes exactly one territory, non-adjacent ids fail with NON_ADJACENT_TERRITORIES, missing dwell_time yields CLARIFICATION_REQUIRED, and the operation writes a new derived alignment and returns a task (async). One ambiguity remains: 'writes a new derived alignment' could be read as non-mutating while destructiveHint=true implies the dissolved territory is gone, which the agent must reconcile.

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 operation and its effect, then constraints and error codes, and every sentence carries operational information. It is dense—several clauses chained into long sentences—and 'The same job rebalances every remaining territory' borders on redundant, but nothing 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 14-parameter, non-idempotent, destructive tool this covers the essentials: required context source, error paths, return shape ('returns a task'), and side effects, and an output schema covers return values. What is left implicit is whether the source TAL survives the merge and whether repeat calls are safe.

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 86%, so the baseline is 3, but the description adds conditional logic the schema only hints at: dwell_time is required when balancing workload, and the TAL can come from either ts_handle or map_session_id. The A/B identity semantics are restated usefully for a destructive operation.

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 (merges a pair of adjacent territories) plus the net effect (N to N-1) and disambiguates the two territory params: b is dissolved, a keeps its id. An agent can distinguish this from territory_split or territory_rebalance without opening the schema.

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

Usage Guidelines4/5

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

Gives a concrete triggering scenario ('when a rep leaves and the neighbors absorb the territory') and hard preconditions (source_tal_id plus a Territory Solution via map_session_id or ts_handle; dwell_time required for workload balance). It does not explicitly name sibling alternatives such as territory_split or territory_rebalance, so routing between structurally similar tools is left partly to inference.

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

All EasyTerritory MCP 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.

Resources

Need Help?