The EasyTerritory MCP Server exposes 43 tools to any MCP-compatible AI agent. Tools are organized into two tiers: Tier 1 goal tools (prefer these — they accomplish a complete user goal in one call) and Tier 2 primitives (compose for edge cases and lower-level operations).
Every territory and map tool requires a guidance_handle — a rotating code obtained from get_guidance. Call get_guidance first in every session. Handle-exempt tools (knowledge search, feedback) do not require it.
Session Entry and Routing
| Tool | Tier | Description |
|---|---|---|
get_guidance | 1 | Returns the operating guide and a rotating guidance handle required by all territory/map tools. Call first in every session. |
discover_intent | 1 | Deterministic router that classifies a user request into a workflow category — returns intent, tool order, clarifying questions, and inlined guidance. |
workflow_advisor | 1 | Validated next-action advisor for multi-step workflows. Pass intent + state, get the correct next tool call. Re-call after each step until done. |
ezt | 1 | Plain-language orchestrator for one-step completion when the granular tool is unclear. Prefer granular tools when you know the step. |
Map and Data
| Tool | Tier | Description |
|---|---|---|
get_map_visualization | 1 | Opens or reuses the Map Component for a Territory Solution. Returns a shareable map_url. First step of all non-headless work. |
ensure_map_viewer | 1 | Confirms a live viewer is connected before pushing compute or selection state. Poll until connected. |
show_map_overlay | 1 | Shows or adds a data layer on the map — ZIPs, counties, accounts, territories, routes. Takes natural language user_request. |
configure_map | 2 | Patches map config: loaded part layers, active TAL, point classifications (color/size/shape), presentation. Also handles point symbology via point_layer_classifications. |
set_map_state | 2 | Low-level MC mode or active TAL switch. Reserved — prefer configure_map for durable config. |
geocode_address | 1 | Geocodes addresses without full account ingest. Cache-first (TomTom → Azure Maps). Use to verify geocode quality before ingest. |
ingest_accounts | 1 | Loads account/location rows as a point layer. Geocodes rows lacking coordinates. Declares metric, workload, dwell, and visit-frequency field metadata. |
request_account_upload | 2 | Stages account rows too large to inline. Returns accounts_handle for ingest_accounts. Supports csv_text, csv_file, or chunked rows with append. |
query_parts | 2 | Retrieves part metadata only (no geometry). Filter, enrich, or count parts before a build. |
Territory Building
| Tool | Tier | Description |
|---|---|---|
auto_build | 1 | Builds N balanced territories from loaded accounts. Modes: fixed_territory_count, fixed_workload_target, scoped_split. Objective blends workload and metrics via bias weights. |
account_build | 1 | Builds territories that mirror an existing CRM grouping field (rep name, territory name, territory code). Conflicts resolved by plurality or configurable policy. |
cluster_points | 1 | Balanced point grouping with CCPD — same build_mode, objective, dwell, and visit-frequency as auto_build. Output is a group_field on points (no TAL, no geography dissolve). Add seed_point_layer to anchor groups to start locations. |
direct_build | 1 | Creates a TAL from explicit part-to-territory assignments (spreadsheet, legacy file, hierarchical territory_path). Stage files with request_assignment_upload first. |
request_assignment_upload | 2 | Stages legacy part-to-territory spreadsheets (Postal Code + Territory/Region/Division). Returns assignments_handle for direct_build. |
isochrone_build | 1 | Generates drive-time or drive-distance areas from one or more origins. Origins × budget bands in one call. Produces a TAL of territories. Needs TomTom or Azure Maps key. |
Territory Management
| Tool | Tier | Description |
|---|---|---|
realign | 1 | Moves parts between leaf territories within one TAL. Supports individual moves, remove_parts, and remove_empty_territories. Followed by geometry re-dissolve and repair. |
request_part_selection | 2 | Starts an interactive map selection task for realign, manual build, or return_list. User selects parts on the map; agent polls get_part_selection. |
get_part_selection | 2 | Polls or retrieves committed part IDs after a selection task. Poll until status=committed, then proceed. |
get_map_selection | 2 | Reads the latest committed MC selection — use when the user started selection from the legend without a prior request_part_selection. |
create_territory_from_parts | 2 | Creates or updates one leaf territory from committed part IDs. Supports conflict_policy=move_from_existing to take parts from another territory. |
delete_territory | 1 | Deletes one leaf territory from a TAL. Collects parts and runs Realign remove_parts internally. To wipe an entire TAL, use delete_tal. |
delete_tal | 2 | Wipes one entire TAL from the TS and open map in one synchronous call. Preserves points, part overlays, and routes. |
Restructure (Split / Merge / Rebalance)
| Tool | Tier | Description |
|---|---|---|
territory_split | 1 | Splits one oversized territory with minimal disruption to the rest of the alignment. Distinct from auto_build scoped_split (balanced from scratch). |
territory_merge | 1 | Merges two adjacent territories and rebalances with minimal disruption. |
territory_rebalance | 1 | Adjusts boundaries to restore balance after data changes. Source assignment is the non-regression baseline — no change if no candidate improves the objective. |
Analysis
| Tool | Tier | Description |
|---|---|---|
analyze | 1 | Computes balance, workload, and compactness metrics for territories. Re-run after any TAL or point change. Supports cross-TAL comparison and hypothetical moves. |
analyze_routes | 2 | Returns per-route facts (drive hours, dwell hours, route workload, stop coordinates) for routes already drawn by calculate_route. Facts only — no capacity or ranking. |
load_analysis_panel | 2 | Renders Analyze JSON in the Map Component bottom dock — single or comparison view. Session-only display; does not mutate the TS. |
Routing and Scheduling
| Tool | Tier | Description |
|---|---|---|
calculate_route | 1 | Drives a known list of stops in the best sequence. Ordered stop_sets, circuit/tour/open_tour formats, stop-priority banding. Returns road distances, drive times, and map geometry. |
schedule_visits | 1 | Expands recurring account cadence across a repeating horizon into daily work clusters under a technician-day workload cap. No TAL, no technician assignment. Pairs with calculate_route for per-day routing. |
Import and Export
| Tool | Tier | Description |
|---|---|---|
export_ts | 2 | Resolves ts_handle to a compact TS v2 project artifact for customer storage. Durable, columnar format (no polygon geometry). |
export_geojson | 2 | Async job: materializes selected TALs, point layers, and routes as a self-contained GeoJSON FeatureCollection with download_url. GIS interchange format. |
import_geojson | 2 | Imports point GeoJSON or EZT-exported territory GeoJSON. Arbitrary territory polygons need part_layer + overlay_policy=’centroid_within’ to assign parts by centroid. |
Delegation
| Tool | Tier | Description |
|---|---|---|
extract_tal_branch | 2 | Extracts a regional subtree for bounded delegate editing. Senior planner sends a branch to a delegate. |
reintegrate_branch | 2 | Merges an approved proposal TS back into master. Sequential merges only; STALE_TS_REVISION if master moved. |
Async Task Management
| Tool | Tier | Description |
|---|---|---|
tasks_get | 2 | Polls status of an async task. Follow next_action exactly: sleep_and_poll → one more poll; consume_result → call tasks_result once. |
tasks_result | 2 | Consumes the terminal result of a completed task. Call exactly once after tasks_get returns completed. Returns handle-only result. |
tasks_cancel | 2 | Cooperatively cancels a running async task. Confirm TS unchanged or partial per the originating tool contract. |
Knowledge and Feedback
| Tool | Tier | Description |
|---|---|---|
submit_feedback | 2 | Logs a quality issue when workflow is blocked, partial, or a workaround was required. Category, severity, and context captured. |
Tool Tiers Explained
Tier 1 — Goal Tools
Tier 1 tools accomplish a complete user goal in one call. Prefer these. Each links to an owning workflow that defines prerequisites, next steps, and common mistakes. Tier 1 tools include routing (get_guidance, discover_intent, workflow_advisor, ezt), map and data (get_map_visualization, ensure_map_viewer, show_map_overlay, geocode_address, ingest_accounts), building (auto_build, account_build, cluster_points, direct_build), management (realign, delete_territory), analysis (analyze), routing (calculate_route, isochrone_build), and scheduling (schedule_visits).
Tier 2 — Primitives
Tier 2 tools compose for edge cases and lower-level operations. Use them to support a Tier 1 goal, not in place of one. Includes map configuration (configure_map, set_map_state), data staging (request_account_upload, request_assignment_upload, query_parts), selection (request_part_selection, get_part_selection, get_map_selection, create_territory_from_parts), territory deletion (delete_tal), restructure (territory_split, territory_merge, territory_rebalance), analysis display (analyze_routes, load_analysis_panel), import/export (export_ts, export_geojson, import_geojson), delegation (extract_tal_branch, reintegrate_branch), async tasks (tasks_get, tasks_result, tasks_cancel), and feedback (submit_feedback).
Build Tool Disambiguation
These tools are not interchangeable:
- auto_build — balanced partition from points (N territories)
- account_build — group by existing CRM attribute (rep name, territory code)
- cluster_points — balanced grouping column on points, no TAL
- direct_build — known part-to-territory file
- schedule_visits — recurring cadence, which day each visit happens (only one with a time dimension)
- isochrone_build — reachable area around fixed origins (a budget, not an objective — divides nothing, balances nothing)
See also: Getting Started, Connecting Your AI Agent, Territory Building with AI, Territory Management & Realignment, Routing & Scheduling, FAQ.
