EasyTerritory MCP

Rebalance Territories

territory_rebalance

Destructive

Rebalances an existing alignment after the account data changed, keeping it as close to the current alignment as possible. Needs source_tal_id and the Territory Solution from map_session_id or ts_handle. point_layer defaults to the alignment's build layer or the only point layer; otherwise CLARIFICATION_REQUIRED (ambiguous_point_layer, with details.point_layers). Workload balance needs dwell_time; zero_workload means no account maps to a part. The current alignment is the baseline: when nothing improves the objective the result is NO_IMPROVING_REBALANCE_FOUND and nothing changes. Writes a new derived alignment. Returns a task with retention_pct and solver_diagnostics.

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

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

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

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

Behavior4/5

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

Annotations declare destructiveHint=true and non-idempotent, but the description clarifies the actual blast radius: it "writes a new derived alignment" rather than mutating in place, and the current alignment acts as a baseline so a no-improvement run leaves everything untouched (NO_IMPROVING_REBALANCE_FOUND). It also surfaces the CLARIFICATION_REQUIRED escape hatch with details.point_layers and the returned task payload (retention_pct, solver_diagnostics). Permission/auth requirements and cost/runtime characteristics are not mentioned.

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?

Six dense sentences, front-loaded with the core action and the baseline-preservation guarantee, then the input sourcing rules, then the ambiguity and degenerate-result cases. No filler, though the point_layer defaulting sentence and the NO_IMPROVING sentence are packed enough to need a second read.

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 12-parameter, destructive, warm-start solver call with an output schema present, the description covers the inputs' sourcing rules, the degenerate outcome, the clarification protocol, and the mutation model. Remaining gaps (interplay of disruption_weight with the objective biases, runtime expectations) are partially absorbed by the high schema coverage and the output schema.

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 already 83%, so the baseline is 3, and the description adds real cross-parameter semantics: dwell_time is required whenever workload balance is in play, point_layer defaults to the alignment's build layer or the sole point layer and produces ambiguity errors otherwise. The tradeoff logic between metric/workload bias and disruption_weight is left entirely to schema text.

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

Purpose4/5

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

"Rebalances an existing alignment after the account data changed, keeping it as close to the current alignment as possible" gives a specific verb, a clear precondition (data changed), and an implicit contrast with cold-start builds (seed_build/auto_build) and with the sibling `realign`. It never names an alternative tool outright, so the distinction is inferred rather than stated.

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?

Prerequisites are spelled out: source_tal_id plus a Territory Solution supplied via map_session_id or ts_handle, and the temporal trigger (after account data changed). It also explains the fallback path for point_layer and what a zero_workload outcome means. It stops short of explicitly comparing against sibling tools like realign or auto_build for the same request.

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?