# EasyTerritory MCP (remote · mcp.easyterritory.ai) Build, balance, realign and analyze sales/service territories; geocode, route, schedule, live map. - Trust score: 76/100 (medium) - Change this week: +3 - Registry status: active - Liveness: live - Owner verified: no - Last scored: 2026-10-07 ## Components - remote · `mcp.easyterritory.ai`: 76/100 (this document), [markdown](https://verifymcp.io/servers/ai-easyterritory-ezt-mcp/mcp.md), [page](https://verifymcp.io/servers/ai-easyterritory-ezt-mcp/mcp) ## Channel facts - Endpoint: `https://mcp.easyterritory.ai/` - Transports: `streamable-http` - Auth: `required` - Version: `0.1.0` ## Trust breakdown How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog) Scored 2026-10-07. - **Endpoint Security**: 89/100 - The endpoint's TLS certificate is valid, in date, and uses a strong key. - Authorisation is enforced on tool calls, advertised via RFC 9728 protected-resource metadata. Discovery is public, which costs nothing: no tool can be invoked without a token. - HTTPS is enforced; there's no plaintext access path. - HSTS check failed: the Strict-Transport-Security header is absent. - DNSSEC check failed: this domain isn't protected by DNSSEC. - The authorisation server offers only Dynamic Client Registration (RFC 7591), which MCP 2026-07-28 deprecated in favour of Client ID Metadata Documents. - **Transport & Reachability**: 100/100 - Verified streamable-http transport via a live MCP handshake. - **Schema Quality & AI Usability**: 69/100 - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name). - AI-judged instruction clarity (good). - Context-footprint check failed: tool/resource definitions use about 21018 tokens (~404/item across 52 items; 47 tools + 5 resources), over budget; trim descriptions and params. - Usage-examples check failed: none of the tools include examples. - **Stability & Change Management**: 26/100 - Stability check failed: schema churn in the 8 days we've observed: 0 tool removals, 1 breaking changes, 0 auth/transport breaks, 0 additions. - **Tool Coverage**: 72/100 - 100% of tools have a non-trivial description (not blank, and not just the tool's name). - 2% of tool parameters carry a description. - Structured output schemas are declared (100% of tools); any adoption earns full credit. - **Tool Safety**: 75/100 - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured. - 0 of 4 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "delete_tal" implies "delete" and declares no destructiveHint at all, which the MCP spec reads as destructive by default. - An AI judge read all 49 captured unit(s) of tool text and found none that tries to manipulate the model reading it. - **Capabilities**: 100/100 - Implements a current MCP spec version (2026-07-28). - Supports UI / widget rendering. ## Install ### How do I install the EasyTerritory MCP server? EasyTerritory MCP is a hosted endpoint at https://mcp.easyterritory.ai/, so there is nothing to install locally. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation. ### Claude ```bash claude mcp add --transport http ai-easyterritory-ezt-mcp 'https://mcp.easyterritory.ai/' ``` ### Cursor ```json { "mcpServers": { "ai-easyterritory-ezt-mcp": { "url": "https://mcp.easyterritory.ai/" } } } ``` ### VS Code ```json { "servers": { "ai-easyterritory-ezt-mcp": { "type": "http", "url": "https://mcp.easyterritory.ai/" } } } ``` ### Codex ```toml [mcp_servers.ai-easyterritory-ezt-mcp] url = "https://mcp.easyterritory.ai/" ``` ### opencode ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "ai-easyterritory-ezt-mcp": { "type": "remote", "url": "https://mcp.easyterritory.ai/", "enabled": true } } } ``` ### OpenClaw ```bash openclaw mcp add ai-easyterritory-ezt-mcp --url 'https://mcp.easyterritory.ai/' --transport streamable-http ``` ### Hermes ```yaml mcp_servers: ai-easyterritory-ezt-mcp: url: "https://mcp.easyterritory.ai/" ``` ### Netclaw ```json { "McpServers": { "ai-easyterritory-ezt-mcp": { "Transport": "http", "Url": "https://mcp.easyterritory.ai/" } } } ``` ### Vellum ```bash assistant mcp add ai-easyterritory-ezt-mcp -t streamable-http -u 'https://mcp.easyterritory.ai/' ``` ### Other ```json { "mcpServers": { "ai-easyterritory-ezt-mcp": { "type": "http", "url": "https://mcp.easyterritory.ai/" } } } ``` The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs. ## Changelog Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims. ### 2026-10-07 (score 76, +1) - [security regression] Stability: 0.17 → fail - [security] The server rewrote its instructions, which are the text every model session reads - [security] Tool “analyze” rewrote its description, which is the text the model reads - [security] Tool “delete_territory” rewrote its description, which is the text the model reads - [security] Tool “ensure_map_viewer” rewrote its description, which is the text the model reads - [security] Tool “set_map_state” rewrote its description, which is the text the model reads - [security] Tool “territory_merge” rewrote its description, which is the text the model reads - [security] Tool “territory_rebalance” rewrote its description, which is the text the model reads ### 2026-10-04 (score 75, +1) No change was recorded against any check on this day. Stability & Change Management went from 13 to 17. That category is still filling its 30-day observation window: 4 days of observed history at the previous scan, 5 at this one. The score rises as the window fills, whether or not the server changes. ### 2026-10-02 (score 74, +1) No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes. ### 2026-09-30 (score 73, +1) - [functional improvement] Stability: unverified → 0.03 ### 2026-09-29 (score 72) First indexed and scored. ## MCP tools (47) ### `get_map_visualization` (~310 tokens) Open Map [Tier 1 — MC-First Entry] FIRST step of non-headless territory work (invariant I-1). When: open a blank map for planning, or open/reuse the user's Map Component for an existing Territory Solution (TS), ts_handle, or completed job. Pass new_project=true to replace the live workspace with an empty project; omitted empty+view reuses the existing project. Optional presentation.view_name: empty | points_only | review | selection (defaults from mode/TS content). Diagnostics: presentation.debug_panel=true. Prerequisites: none (idempotent per user_id). Next: hand user map_url, then ensure_map_viewer until viewer_status.connected. Dual surface (same map_session_id, one map): Apps-capable hosts render this map in chat from ui://easyterritory/map-viewer (_meta.ui.resourceUri); every other client — including Cursor — opens map_url in a browser tab. map_url is always returned. Do not open a second surface or call this tool again to 'fix' a map. Scenarios: MC-000, MC-001, MV-001, S004. Input parameters: - `active_tal_id` - `expiry_seconds` - `guidance_handle` - `interaction_flags` - `job_id` - `mode` (string) - `new_project` (boolean) - `presentation` - `ts` - `ts_handle` - `user_id` ### `get_guidance` (~191 tokens) Get Startup Guidance [Tier 1 — Startup Guide + Handle] CALL THIS FIRST. Read-only. When: session start, after blocked_by=guidance_required, or when the shared rules are unclear. Returns result.text (the short cross-tool brief, same text as server instructions), result.guidance_handle (the rotating code every territory/map tool requires), result.server_version (this server's product version; the same string as serverInfo.version), and result.seat (plan standard|trial, key_expires_at, and quota_remaining for geocode/route/isochrone — tell a trial user when the trial or an allowance is close to running out). Per-tool rules are on that tool's description. Workflow essays are inlined as guidance on discover_intent, workflow_advisor, and blocked_by. Exempt: get_guidance, submit_feedback, discover_intent, workflow_advisor, ep_* tools. ### `discover_intent` (~435 tokens) Discover Workflow Intent [Tier 1 — Router] Deterministic entry point for ambiguous or open-ended territory requests. When: the user's goal or build type is unclear and you want the correct workflow before acting. Prerequisites: none (static keyword routing; no compute). Returns an intent_category, the recommended tool order, the Tier 1 tool + Tier 2 alternatives, required_inputs, clarifying_questions to ask when inputs are missing, a guidance_uri (ezt://guidance/workflows/{name}) for the full atom, and `guidance` — the same EMEP atom inlined as {uri, title, excerpt, truncated}, so you do NOT need a second resources/read to get the workflow text. Use it to disambiguate auto_build vs account_build vs direct_build and to route realign / restructure / analyze / delegation / geocode-ingest / load-part-layer-on-map (add zips, show zip codes) / route-stops (drive a list of stops in the best order) / reachable-area (a drive-time or drive-distance area around origins — service area, catchment, coverage, isochrone, which routes to isochrone_build) / periodic-scheduling (a recurring cadence — 'every 30 days', 'twice a month' — and which day each visit lands on, which routes to schedule_visits, never auto_build or cluster_points) / push-to-designer (an EasyTerritory Designer rolodex project from a TS: export_geojson then POST FromTerritorySolution to create or PUT .../Projects/{projectId}/... to update; territories, points, and routes import; ezt_pat_; there is no MCP push tool) / pull-from-designer (a Designer rolodex project into the MCP: GET REST/Agent/Projects then GET .../Projects/{projectId}/TerritorySolution with ezt_pat_, then import_geojson geojson_gzip; there is no MCP pull tool). Scenarios: AB-016, ACB-003, wrong-build-tool. Input parameters: - `context` - `user_request` (string, required) ### `workflow_advisor` (~602 tokens) Get Next Workflow Step [Tier 1 — Workflow Advisor] Deterministic read-only next-action advisor for multi-step workflows. When: you know the intent (use discover_intent first if not) and want the validated next tool call instead of guessing the order. Prerequisites: none (static state machine; executes nothing). Pass intent_category (builds: build_from_accounts | account_grouping | known_assignments; edits: realign_existing | restructure; map overlay: load_part_layer for add/show ZIP or part layer; routing: route_stops for driving a known list of stops; reachable areas: reachable_area for a drive-time or drive-distance area around origins, with isochrone_build accepted as an alias; scheduling: periodic_scheduling for a recurring cadence, with schedule_visits accepted as an alias), agent-supplied state (viewer_connected, point_layer, part_layer, tal_present, analysis_fresh; realign adds selection_requested/selection_committed/realign_applied; restructure adds source_tal_id), and optional inputs (builds: part_layer, territory_count, grouping_field, assignments_handle, tal_label; realign: tal_id, moves or realign_operation+part_ids, to_territory_id, analysis_requested; restructure: operation=split|merge|rebalance, source_tal_id, target_territory_id, territory_id_a/territory_id_b; load_part_layer: user_request for ZIP inference; route_stops: route_type=circuit|tour|open_tour, start, stop_sets, end for tour, stops_need_ingest when the stops are not in the TS yet; reachable_area: origins, bands, part_layer, travel_mode=car|truck, origins_need_ingest when the origins are not in the TS yet — the advisor never invents a budget; periodic_scheduling: visit_frequency_field, frequency_unit, dwell_time or dwell_minutes/dwell_hours, daily_capacity or daily_capacity_hours, horizon_days, max_buckets_per_day — the advisor reports cadence/dwell/capacity as missing rather than inventing them). Returns next_tool + drafted next_args, missing_inputs, blocked_by, remaining_steps, guidance_uri, and `guidance` (th… Input parameters: - `inputs` - `intent_category` (string, required) - `state` ### `ep_search` (~147 tokens) Search Expert Pack [Knowledge Retrieval] Semantic search over the EZT MCP Expert Pack (EMEP) for targeted workflow guidance, concepts, interfaces, and common mistakes. When: you are unsure which tool or order to use, hit an error, or need product-specific domain context before acting. Returns ranked markdown chunks with source files; atoms pulled in via `requires` are flagged requires_expanded. Degrades to the ezt://guidance/... resources if retrieval is unavailable. Examples: 'build balanced territories from accounts', 'viewer not connected before compute', 'auto_build vs account_build'. Input parameters: - `max_results` (integer) - `query` (string, required) - `tags` - `type` ### `ep_list_topics` (~59 tokens) List Expert Pack Topics [Knowledge Retrieval] List EMEP topics grouped by type (concept, workflow, interface, troubleshooting, decision). Use to discover what guidance exists before ep_search, or to browse the pack. Optional `type` filter. Input parameters: - `type` ### `ep_graph_traverse` (~85 tokens) Traverse Expert Pack Links [Knowledge Retrieval] Traverse the EMEP knowledge graph from a topic file (e.g. 'workflows/realign-by-selection.md') to find related guidance, up to `depth` hops. Returns no edges unless the pack ships a _graph.yaml. Input parameters: - `depth` (integer) - `edge_kinds` - `file_path` (string, required) ### `ensure_map_viewer` (~225 tokens) Wait for Map Viewer [Tier 1 — MC-First Gate] When: after get_map_visualization returns map_url and before any compute, build, analyze, or selection work with a human in the loop. Prerequisites: map_session_id from get_map_visualization. Next: ingest, configure_map, build, realign, or analyze once viewer_status.connected. Surface-agnostic: the in-chat MCP App shell connects the same session over the same SSE channel, so this gate works unchanged whether the human is looking at the in-chat map or the map_url tab. Do not skip it on an Apps host. wait_seconds blocks at most 30 s per call (larger values are clamped; the result reports requested_wait_seconds and max_wait_seconds). On VIEWER_NOT_CONNECTED, call again with the same map_session_id while the user opens map_url. Scenarios: MV-001, I-1. Input parameters: - `guidance_handle` - `map_session_id` (string, required) - `poll_interval_ms` (integer) - `wait_seconds` (number) ### `submit_feedback` (~191 tokens) Submit Feedback [Tier 2 — Quality Feedback] When: workflow blocked, partial, workaround required, confusing tool response, or missing capability/docs. Prerequisites: none. Next: continue or end session after acknowledgement. Scenarios: GC-006. No secrets, credentials, raw customer data, or PII. Do not paste Territory Solution JSON, GeoJSON FeatureCollections, or account/CSV tables — those blocks are stripped. Input parameters: - `category` - `client_name` - `client_version` - `confidence` - `context_summary` - `correlation_id` - `expected_capability` - `include_context` (boolean) - `related_product_area` - `related_tool` - `session_id` - `severity` - `suggested_improvement` - `user_goal` (string, required) - `what_happened` (string, required) ### `query_parts` (~164 tokens) Query Territory Parts [Tier 2 — Part Metadata] When: enrich or filter parts before build, or inspect attributes without geometry. Prerequisites: part_layer from ezt://part-layers. Pass exactly one of filter (e.g. {state_abbr: TX}) or part_ids; neither or both is INVALID_REQUEST. To check that a part layer exists, read ezt://part-layers instead of probing with an empty query. Next: direct_build, configure_map, or agent-side join before build. Scenarios: DS-002. Returns part_id and attributes only; no geometry. Input parameters: - `filter` - `guidance_handle` - `max_results` (integer) - `page_token` - `part_ids` - `part_layer` (string, required) ### `direct_build` (~345 tokens) Build Territories from Assignments [Tier 1 — Known Assignments Builder] When: user has explicit part-to-territory assignments (spreadsheet, legacy file, hierarchical territory_path). assignments_handle must be a server upload handle (aup_...) from request_assignment_upload — csv_text/csv_file/assignments, or a POST of the CSV file to its key-less result.upload_url. Legacy spreadsheets (Postal Code + Territory/Region/Division) are auto-mapped when staged. Conflicting duplicate part_ids default to duplicate_part_policy=keep_first (first wins). Prerequisites: part_layer chosen; viewer connected for MC-first; ts/ts_handle optional. Not for account point locations—use ingest_accounts. Not for balanced partitioning—use auto_build. Not for attribute grouping—use account_build. Next: verify TAL in MC (MC-011), analyze + load_analysis_panel. Scenarios: DB-001..005, MC-011. Input parameters: - `assignments` - `assignments_handle` - `duplicate_part_policy` (string) - `expected_revision` - `guidance_handle` - `map_session_id` - `missing_part_policy` (string) - `part_layer` (string, required) - `repair_policy` (string): 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). r… - `tal_id` - `tal_label` (string, required) - `ts` - `ts_handle` ### `auto_build` (~1221 tokens) Auto-Build Territories [Tier 1 — Balanced Territory Builder] When: partition account points into N balanced territories over a part layer (for example, ten territories; Mode A count, Mode B workload target, Scoped Split). Execution gate: after sizing, balance, dwell, and scope are known, call THIS tool immediately — searching the catalog, get_guidance, or polling Tasks never starts a build. A successful response with a new task_id is the only proof of submit; do not claim started/restarting until then. Then follow do_this_next only with that new task_id. When workflow_advisor returns next_tool=auto_build, call auto_build next. Canonical example — 3 TX ZIP territories, workload-only, 30-min dwell: build_mode={mode: fixed_territory_count, territory_count: 3}, objective={workload_bias: 100}, dwell_time={type: scalar, value: 30, unit: minutes}, part_scope=explicit, part_filter={state_abbr: TX}, map_session_id=. Omit ts and ts_handle when the session id argument is already set. That session is the TS. Do not repost inline ts. build_mode.mode must be exactly one of: fixed_territory_count, fixed_workload_target, scoped_split. For workload targets (e.g. 40-hour territories), use build_mode={mode: fixed_workload_target, target_workload: 40} (territories only approximate the target). ALWAYS ask for dwell/onsite time before calling — Auto Build always computes territory workload hours (drive + dwell), even when balancing on a metric or account count. Pass dwell_time only after they confirm a column ({type: field, field, unit}) or scalar ({type: scalar, value, unit}). Never invent default dwell such as 1 hour or 30 minutes per visit. Server rejects auto_build without resolved dwell_time (CLARIFICATION_REQUIRED). VISIT FREQUENCY: when the point layer has a visit-frequency column, ask whether to aggregate workload across a schedule period (pass visit_frequency_field) or ignore it (pass ignore_visit_frequency=true). Do not inherit the column silently. If no visit-frequency column exists, omit… Input parameters: - `build_mode` - `dwell_time` - `expected_revision` - `guidance_handle` - `ignore_visit_frequency` - `map_session_id` - `objective` - `output_mode` (string): tal is the default. assignments returns assignments_artifact plus an authenticated download_url; no ts_handle, tal_id, or map_refresh. - `part_filter` - `part_ids` - `part_layer` (string, required) - `part_scope` - `point_layer` (string, required) - `repair_policy` (string): 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). r… - `tal_label` (string, required) - `ts` - `ts_handle` - `visit_frequency_field` ### `cluster_points` (~829 tokens) Cluster Points [Tier 1 — Balanced Point Grouping] Partition one ingested point layer directly into balanced point groups with CCPD, without using ZIPs/counties or creating a TAL. The tool adds group_field (default group_id) to every point and color-classifies that field in the linked Map Component. That write replaces the layer's existing color classification (including a leftover color_classification ramp). Size and shape channels stay. Keep a prior metric as a second encoding with configure_map channel=size or channel=shape after this job — never a second color classification on the same layer. Example — five TX point groups balanced on workload with confirmed 30-minute dwell: point_layer=accounts, build_mode={mode: fixed_territory_count, territory_count: 5}, objective={workload_bias: 100}, dwell_time={type: scalar, value: 30, unit: minutes}. Prerequisite: ingest_accounts completed for point_layer. Omit ts and ts_handle when the session id argument is already set. That session is the TS. Ask the same sizing, balance, bias, visit-frequency, and dwell questions; workload means in-group drive time plus dwell, never a metric column. Never invent dwell. build_mode supports fixed_territory_count and fixed_workload_target only. SUBSET: a named state or region on an already-ingested layer — Florida schools, TX accounts only — uses point_filter on the first call, e.g. point_filter={STATE: FL}. Keys are point properties (one value or a list). Do not re-ingest a filtered extract. Do not pass part_filter or part_scope (those belong to ZIP/part tools). Do not cluster the national layer. Unmatched points stay on the layer with group_field cleared and appear as an Ungrouped legend class. The 10,000-point cap applies after the filter. Empty match is EMPTY_POINT_FILTER; unknown property is UNKNOWN_POINT_PROPERTY. SEEDING BIAS (start locations): when the groups should line up with a set of start locations — technician homes, depots, branch offices — pass seed_point_layer=. It must be… Input parameters: - `build_mode` - `dwell_time` - `expected_revision` - `group_field` (string) - `group_label_prefix` (string) - `guidance_handle` - `map_session_id` - `metric_fields` - `objective` - `point_filter` - `point_layer` (string, required) - `seed_attraction` - `seed_point_layer` - `ts` - `ts_handle` - `visit_frequency_field` ### `schedule_visits` (~605 tokens) Schedule Visits [Tier 1 — Periodic Scheduling] When: accounts carry a recurring cadence (every 7 days, twice a month) and the user asks which day each visit happens. Expands demand across a repeating horizon and packs it into daily work clusters (buckets) under one technician-day workload cap. This tool decides the day. Neighbors: auto_build, cluster_points, calculate_route. When the user said route and a visit-frequency column exists, confirm they want a schedule, not calculate_route, before calling. It creates no TAL and assigns no technician. Prerequisite: ingest_accounts completed for point_layer with the cadence column declared. Omit ts and ts_handle when the session id argument is already set. That session is the TS. An undeclared column fails with UNDECLARED_FIELD. Required: point_layer, visit_frequency_field, dwell_time, daily_capacity. Ask the user for dwell and the daily cap; never invent them. frequency_unit=interval_days means the value is the maximum days between visits (so a 3-day cadence in a 14-day horizon is 5 visits, not 4); visits_per_horizon means the count across the horizon. Values in never_visit_values (default 0, null, empty) are excluded and reported in excluded_accounts, never silently dropped. Example — weekly and biweekly accounts across 8-hour technician days: point_layer=accounts, visit_frequency_field=service_interval_days, dwell_time={type: scalar, value: 45, unit: minutes}, daily_capacity={mode: not_to_exceed, hours: 8}, max_buckets_per_day=3. bucket_workload_hours is in-bucket drive plus dwell with NO visit-frequency multiplier: it is neither territory workload nor route_workload_hours — never sum or compare them. Re-running with the same visit_layer_name replaces that schedule in place; a different name adds a second one for comparison. After submission, follow do_this_next with the returned task_id: sleep exactly sleep_ms while next_action=sleep_and_poll, fetch the result once on consume_result, and stop on stop_error. Next: calculate_route over… Input parameters: - `cadence_flexibility_pct` - `daily_capacity` - `dwell_time` - `emit_visit_layer` (boolean) - `expected_revision` - `frequency_unit` (string) - `guidance_handle` - `horizon` - `map_session_id` - `max_buckets_per_day` - `never_visit_values` - `objective` - `point_layer` (string, required) - `schedule_label` - `ts` - `ts_handle` - `visit_frequency_field` (string, required) - `visit_layer_name` ### `account_build` (~507 tokens) Build Territories by Account Field [Tier 1 — Attribute Grouping Builder] When: territories should mirror an account attribute column from CRM exports (rep name, territory_name, territory code). Prerequisites: ingest_accounts with grouping column; part_layer chosen; viewer connected. Omit ts and ts_handle when the session id argument is already set. That session is the TS. Numeric codes are labels, not balance metrics; scoped builds use in-scope accounts only. Part scope defaults to bbox_intersect (bbox proximity of ingested accounts). When the user names a state/region ('TX ZIPs only'), pass part_scope=explicit and part_filter={state_abbr: TX} — not bbox_intersect. Scope fields are top-level part_filter/part_ids. Progress: linked tasks publish live subphases on Tasks status / MC overlay (grouping → radial seeds → inflate → empty-part assign → interlock polish) with cooperative cancel — same poll loop as auto_build (next_action / sleep_ms). VISIT FREQUENCY: when a cadence column is declared, pass visit_frequency_field to scale workload or ignore_visit_frequency=true for one visit per cycle — do not inherit the column silently. Modern form-capable clients (protocol >= 2026-07-28) may be prompted in-band for missing grouping_field / part_layer / tal_label; legacy hosts keep required-arg / INVALID_REQUEST errors. Next: analyze + load_analysis_panel. Scenarios: ACB-001..004, MC-011. Input parameters: - `conflict_policy` (string) - `expected_revision` - `grouping_field` - `guidance_handle` - `ignore_visit_frequency` - `map_session_id` - `output_mode` (string): tal is the default. assignments returns assignments_artifact plus an authenticated download_url; no ts_handle, tal_id, or map_refresh. - `part_filter` - `part_ids` - `part_layer` - `part_scope` - `point_layer` (string, required) - `repair_policy` (string): 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). r… - `tal_label` - `ts` - `ts_handle` - `visit_frequency_field` ### `realign` (~540 tokens) Realign Parts [Tier 1 — Realign] When: move parts between leaf territories within ONE TAL. Prerequisites: existing TAL plus ONE current TS reference: map_session_id (preferred for an open MC), ts_handle, or ts; expected_revision is optional optimistic concurrency (STALE_TS_REVISION → reload and retry). For a committed ad-hoc map selection, call get_map_selection(map_session_id), then pass moves=[{part_id, to_territory_id}] for each returned selection.part_ids plus tal_id and the same map_session_id. Do not repost the full TS and do not start another selection. to_territory_id must be a leaf territory_id (prefer created_territory.territory_id / leaf_territories / legend catalog). A display-name alias is accepted only as an exact unique match to the leaf's actual name (e.g. 'Territory 3' or 'T1' when that is the name) — do NOT invent shorthand expansions (T3 ≠ Territory 3; no T→Territory mapping). It is NOT tal_id. On UNKNOWN_TERRITORY_ID / AMBIGUOUS_TERRITORY read error.details.available_leaf_territories and stop guessing; if the spoken destination is still unclear, ask the user which leaf (id or exact name). Visual moves with a destination known in advance: request_part_selection with purpose=realign. Structural rebalance: territory_split/merge/rebalance. Next: verify the live map refresh. Run analyze + load_analysis_panel only when the TS has a point layer (I-2). For a geography-only ZIP/part edit, skip analyze unless the user requested AN-004; do not create a NO_POINT_LAYER failure after a successful edit. Full atom: ezt://guidance/workflows/realign-by-selection. Scenarios: RL-001..013, S001, MC-004, EV-001. Input parameters: - `expected_revision` - `guidance_handle` - `map_session_id` - `moves` - `part_ids` - `part_layer` - `realign_operation` - `remove_empty_territories` (boolean) - `repair_policy` (string): 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). r… - `tal_id` (string, required) - `ts` - `ts_handle` ### `delete_tal` (~261 tokens) Delete Alignment [Tier 1 — Delete TAL] When: wipe one whole Territory Alignment Layer (user language: territory layer, alignment, all territories, active alignment — not only 'TAL') from the TS and open map (e.g. 'remove the territory layer', 'wipe all territories', 'remove the alignment', 'clear tal-tx-10t before rebuild'). Prerequisites: map_session_id for an open MC (preferred), else ts_handle; plus tal_id (or an exact unique TAL label). NOT for deleting one leaf territory — that is delete_territory. Do NOT N× delete_territory to wipe an alignment. Synchronous: no task_id / no Realign progress overlay. Points, part-layer overlays, and routes stay; active_tal_id becomes a remaining TAL, __points__, or __empty__. Already-absent returns ok with already_absent=true. Ambiguous label returns AMBIGUOUS_TAL. Next: verify the legend dropped the alignment, then auto_build / account_build / direct_build when rebuilding. Scenarios: HITL-057, T-134. Input parameters: - `guidance_handle` - `map_session_id` - `tal_id` (string, required) - `ts_handle` ### `delete_territory` (~419 tokens) Delete Territory [Tier 1 — Delete Territory] When: delete one leaf territory from an existing TAL (e.g. 'delete T1', 'remove territory West'). Prerequisites: ONE current TS reference — prefer map_session_id for an open MC, else ts_handle or ts; tal_id; territory_id (stable leaf id from created_territory.territory_id / leaf_territories preferred, or an exact unique display name — do not invent shorthand like T3 for Territory 3; ask if unclear). Do NOT invent part_ids or call auto_build. This tool collects the leaf's part_ids and runs Realign remove_parts + remove_empty_territories (same engine as RL-013). To wipe an entire TAL / alignment before rebuild, call delete_tal instead — never N× this tool. When a rep leaves and the neighbors should take over the territory, call territory_merge instead — this tool leaves the deleted territory's parts unassigned. Already-absent territories return ok with already_absent=true (no job). Next: follow the returned Tasks status operation until completed, call its result operation once, then verify the open map legend no longer lists the territory AND the territory fill/outline is gone from the canvas (not just the legend) before claiming success. Geography-only delete does not require Analyze. Scenarios: feedback delete-territory, RL-013 wrapper, T-087 last-leaf paint clear. Input parameters: - `expected_revision` - `guidance_handle` - `map_session_id` - `part_layer` - `repair_policy` (string): 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). r… - `tal_id` (string, required) - `territory_id` (string, required) - `ts` - `ts_handle` ### `territory_split` (~328 tokens) Split Territory [Tier 1 — Minimal-Disruption Split] When: split one oversized territory with minimal disruption to the rest of the alignment. Prerequisites: existing TAL with target territory; viewer connected for MC-first. Open MC preferred args: map_session_id + source_tal_id + target_territory_id (live session TS is authoritative — do not repost GeoJSON). Headless: ts_handle or Compact/GeoJSON ts. Distinct from auto_build Scoped Split (balanced-from-scratch). Modern form-capable clients may be prompted in-band for missing source/target ids (and unresolved workload dwell); legacy hosts keep CLARIFICATION_REQUIRED. Next: compare derived TAL in MC, analyze disruption_summary. Scenarios: SP-001..004. Input parameters: - `balance_tolerance` - `disruption_weight` - `dwell_time` - `guidance_handle` - `map_session_id` - `new_tal_label` - `new_territory_label` - `objective` - `part_layer` - `point_layer` - `repair_policy` (string): 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). r… - `source_tal_id` - `target_territory_id` - `ts` - `ts_handle` - `visit_frequency_field` ### `territory_merge` (~424 tokens) Merge Territories [Tier 1 — Minimal-Disruption Merge] When: merge two adjacent territories and rebalance with minimal disruption — including a rep who quits or leaves (their territory is absorbed by its neighbors) and going from N to N-1 territories on an existing alignment. Pass the territory that goes away as territory_id_b and one adjacent neighbor as territory_id_a (it keeps its id); the same job then rebalances every remaining territory, so do not follow it with territory_rebalance. Not delete_territory (that leaves the parts unassigned) and not a new auto_build (that discards the alignment). One call removes one territory. On NON_ADJACENT_TERRITORIES pick another neighbor. Prerequisites: adjacent territory_id_a and territory_id_b in source TAL. Open MC preferred args: map_session_id + source_tal_id + territory_id_a/b (live session TS is authoritative — do not repost GeoJSON). Headless: ts_handle or Compact/GeoJSON ts. Modern form-capable clients may be prompted in-band for missing ids / workload dwell; legacy hosts keep CLARIFICATION_REQUIRED. Next: verify merged TAL in MC, analyze. Scenarios: MG-001..005, EV-001. Input parameters: - `balance_tolerance` - `disruption_weight` - `dwell_time` - `guidance_handle` - `map_session_id` - `new_tal_label` - `objective` - `part_layer` - `point_layer` - `repair_policy` (string): 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). r… - `source_tal_id` - `territory_id_a` - `territory_id_b` - `ts` - `ts_handle` - `visit_frequency_field` ### `territory_rebalance` (~467 tokens) Rebalance Territories [Tier 1 — Minimal-Disruption Rebalance] When: underlying account data changed but alignment should stay close to current (MDR). Open MC preferred args: map_session_id + source_tal_id (+ objective/dwell) — the live session TS is authoritative; do not invent a ts_handle or repost multi-MB GeoJSON when a map session is open. Headless: ts_handle or Compact TS v2 / GeoJSON ts (both valid). Prerequisites: source TAL, refreshed point_layer; viewer connected for MC-first. point_layer may be omitted: the source TAL's build point layer, else the TS's only point layer, is used. CLARIFICATION_REQUIRED details.reason=ambiguous_point_layer (pass point_layer from details.point_layers) or zero_workload (workload_bias>0 but no account maps to a part — check point_layer and dwell; never rerun as is). The source assignment is the non-regression baseline: if no generated candidate improves the requested objective, the derived TAL stays unchanged and returns NO_IMPROVING_REBALANCE_FOUND. Read solver_diagnostics for source/generated/accepted objectives and convergence. Modern form-capable clients may be prompted in-band for missing source_tal_id / uninferable part_layer / unresolved workload dwell; legacy hosts keep CLARIFICATION_REQUIRED (HITL-025). Next: report retention_pct and diagnostics, then analyze before/after with analysis_panel=single. Scenarios: RB-001..005, EV-003. Input parameters: - `balance_tolerance` - `disruption_weight` - `dwell_time` - `guidance_handle` - `map_session_id` - `new_tal_label` - `objective` - `part_layer` - `point_layer` - `repair_policy` (string): 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). r… - `source_tal_id` - `ts` - `ts_handle` - `visit_frequency_field` ### `extract_tal_branch` (~157 tokens) Extract Alignment Branch [Tier 1 — Delegation Extract] When: senior planner sends a regional subtree to a delegate for bounded editing. Prerequisites: master TS with hierarchical TAL; branch rollup or path identified. Next: store branch extract + branch_metadata; delegate opens MC on extract only. Scenarios: DL-001, DL-002. Input parameters: - `branch_rollup_territory_id` - `branch_territory_path` - `delegate_ref` - `exclude_locked` (boolean) - `expected_content_hash` - `expected_revision` - `guidance_handle` - `map_session_id` - `tal_id` (string, required) - `ts` - `ts_handle` ### `reintegrate_branch` (~155 tokens) Reintegrate Alignment Branch [Tier 1 — Delegation Reintegrate] When: merge an approved proposal TS into master. Prerequisites: branch_metadata, expected_master_revision; proposal TS at current lineage. STALE_TS_REVISION if master moved—request fresh extract. Sequential merges only. Next: refresh master Analysis panel (I-2). Scenarios: DL-003, DL-004, DL-006. Input parameters: - `branch_metadata` (object, required) - `expected_master_content_hash` - `expected_master_revision` (integer, required) - `guidance_handle` - `map_session_id` - `master_ts` - `master_ts_handle` - `proposal_ts` - `proposal_ts_handle` ### `request_part_selection` (~366 tokens) Request Part Selection [Tier 2 — Human Spatial Input] When: Monica selects parts on the map for realign, manual territory build, or return_list. Prerequisites: MC-first + viewer connected; part_layer; active TAL when realigning. Poll loop: after submit, poll get_part_selection(selection_task_id) using recommended_poll_delay_ms from the response (or scripts/wait_part_selection.py) until status=committed — never ask the human to type committed/done/go. User-initiated path: Monica may also start select mode from the MC legend finger icon on a part-layer row (no prior request_part_selection). When the user refers to 'my selection' / 'the parts I selected', read the open map session's latest committed selection via get_map_selection(map_session_id) or get_part_selection using active_selection_task_id from ezt://map-sessions/{id}/state — do not ask them to select again. Next: realign, create_territory_from_parts, or analyze with selection.part_ids. Dual surface: in an Apps-capable host the human selects on the in-chat map (ui://easyterritory/map-viewer); otherwise they select in the map_url tab. The commit poll loop above is identical on both surfaces. Scenarios: S001, MC-004..006, RL-006..013. Input parameters: - `active_tal_id` - `destination_territory_id` - `expiry_seconds` - `guidance_handle` - `new_territory` - `part_layer` (string, required) - `prompt` - `purpose` (string) - `realign_operation` - `remove_empty_territories` (boolean) - `ts` - `user_id` ### `get_part_selection` (~208 tokens) Get Part Selection [Tier 2 — Selection Poll] When: poll or retrieve committed part IDs after request_part_selection OR after Monica starts selection from the MC legend finger icon. Prerequisites: selection_task_id from request_part_selection or from map session state (active_selection_task_id on ezt://map-sessions/{id}/state). Poll loop: while status=awaiting_user_selection, sleep recommended_poll_delay_ms (fallback poll_interval_ms, min 250ms) and poll again until status=committed, expired, or cancelled. Response includes do_this_next and poll_loop while awaiting. If the user already committed and says 'add my selection to …', call once for the committed task (or use get_map_selection) and proceed — do not start a new selection. Next: realign, create_territory_from_parts, or analyze scoped to selection.part_ids. Scenarios: AN-007, RL-008. Input parameters: - `guidance_handle` - `selection_task_id` (string, required) ### `create_territory_from_parts` (~540 tokens) Create Territory from Parts [Tier 2 — Territory From Parts] When: create or update one leaf territory from committed part IDs (manual MC-005 build or RL-011/012). Prerequisites: part_ids from selection or agent list; part_layer; viewer connected. Pass map_session_id for the open MC — the server loads that session's TS, appends the new TAL, and rebinds the same session before map_refresh (do not call get_map_visualization just to show the new territory). If result.map_refresh.notified is false or status is rebind_required, call get_map_visualization(job_id=). With no open MC, pass ts_handle from the prior result (never repost inline ts when a handle exists); the new TAL is appended to that TS and the result returns a new ts_handle. map_session_id wins when both are passed. Completed result includes created_territory.territory_id, leaf_territories, and selection_summary (requested/unique counts plus duplicate_part_ids) — territory_name is a display label only (e.g. T1 → territory_id like tal-t1-t1). Later realign into this territory MUST use created_territory.territory_id (preferred) or the exact leaf display name when unique; never invent shorthand (T3 ≠ Territory 3) — if unclear, ask which leaf from leaf_territories. DWELL: this tool creates a NEW TAL and does not inherit dwell_time from a prior auto_build. Dwell is NOT required to create the territory (same as direct_build). Optional dwell_time={type:scalar,value,unit} stamps build_provenance for later Analyze. Without dwell, Analyze still runs and reports every other statistic but OMITS workload (result.workload_omitted) — present the stats, then relay its ask_user sentence; never invent a default (including 30 minutes). Modern form-capable clients may be prompted in-band for dwell when a hydrated TS shows points without dwell provenance; declining still allows create (HITL-038). Next: repeat for additional territories, realign with created_territory.territory_id, or analyze with confirmed dwell_time. Scenarios: MC-005, RL-011, RL… Input parameters: - `conflict_policy` - `dwell_time` - `guidance_handle` - `map_session_id` - `part_ids` (array, required) - `part_layer` (string, required) - `tal_id` - `territory_name` (string, required) - `territory_path` - `ts` - `ts_handle` ### `analyze` (~917 tokens) Analyze Territories [Tier 1 — Analysis] When: balance diagnostics, cross-TAL comparison, or post-mutation facts. Accepts ts, ts_handle, or completed job_id (inline ts or result.ts_handle from prior compute jobs), or map_session_id alone to analyze the open map as it is now, including points ingested after the build. A job_id or ts_handle is that job's snapshot and wins when both are passed, except when the snapshot has no points and the open map does: then the live map is analyzed and the result warns ANALYZED_LIVE_SESSION. Prerequisites: TAL exists; re-run after any TAL or point change (I-2)—never treat stale analysis as current. Returns JSON facts and presentation guidance URI; no prose. metrics: omit to analyze all declared point-layer columns, or pass explicit names. System dimensions (always valid, not point columns): workload (territory hours; alias total_workload_hours), account_count. Point columns must be fields declared at ingest (metric_fields/workload_fields, e.g. Revenue, Units Sold); undeclared columns are discarded at ingest and fail with UNDECLARED_FIELD — re-ingest with the column declared to analyze it. Response includes available_metrics. METRIC COLUMNS ALWAYS RENDER: the territory_metric_grids (and the MC dock) carry Total Count plus a Total column for EVERY declared metric_fields column of the point layer, in declaration order, even when metrics names only account_count or workload — a count-only panel is never the correct outcome when metrics are declared. Declared names may be bare strings (Designer pull) or {field,label,type} objects (ingest). Metric cells are parsed leniently: '14,651', '$1,200.50', and padded strings sum as numbers. DWELL / WORKLOAD (T-171): workload hours need onsite/dwell time — request dwell_time, TAL build_provenance.dwell_time (auto_build), or the point layer's dwell_time_field. When none resolves, Analyze STILL RUNS and reports counts, metrics, classification breakdowns, and balance on those dimensions; workload is OMITTED (no… Input parameters: - `analysis_panel` - `compare_tals` (boolean) - `dwell_time` - `guidance_handle` - `hypothetical_moves` - `job_id` - `map_session_id` - `max_depth` - `metrics` - `part_layer` - `scope` - `tal_ids` - `ts` - `ts_handle` - `visit_frequency_field` ### `ingest_accounts` (~1284 tokens) Ingest Accounts [Tier 1 — Data Intake] When: load/add account/location rows or account CSV point data into a TS point layer. ALWAYS before account-derived builds (auto_build, account_build). Prerequisites: MC-first + viewer connected when human verifies points; ts/ts_handle optional. Geocodes rows lacking valid coordinates (accept_suboptimal_geocodes defaults true for bulk address-only CSVs). Recognized address columns: address/address_line1/street, city, state, postal columns, plus common CRM headers (e.g. Address 1: Street 1). Coordinate passthrough accepts case-insensitive GIS headers latitude/lat/LAT and longitude/lon/lng/long/LON (no rename required); pass explicit latitude_field/longitude_field for other headers (e.g. Address 1: Latitude). If unused numeric lat/lon-like columns exist and ingest would otherwise bulk-geocode, the job fails fast with CLARIFICATION_REQUIRED / blocked_by=needs_coordinate_fields — set latitude_field/longitude_field or force_regeocode=true; never wait on a national geocode crawl. After submit, if the first Tasks status shows coordinate_passthrough_count=0 with a large geocode_query_count on a file that had coord-like columns, call tasks/cancel or tasks_cancel and fix headers/fields. id_field must be a UNIQUE business key (default row_id). Never use label/name columns — duplicates fail with blocked_by=needs_unique_row_id. If no unique column exists, omit id_field (server synthesizes row-1, row-2, … when row_id is absent) or synthesize a unique row_id client-side before staging. Before this call, inspect headers/samples for metric, dwell-time, and visit-frequency columns. Pass confirmed business metrics as metric_fields and confirmed workload roles as workload_fields plus visit_frequency_field/dwell_time_field so downstream tools can reuse point-layer metadata. If no visit-frequency column exists, omit visit_frequency_field; do not ask for an average/default frequency. DECLARED FIELDS ARE THE RETENTION CONTRACT: the TS keeps only id, coordinates, lab… Input parameters: - `accept_suboptimal_geocodes` (boolean) - `accounts_handle` - `country_hint` - `display_fields` - `dwell_time_field` - `force_regeocode` (boolean) - `grouping_fields` - `guidance_handle` - `id_field` (string) - `label` (string) - `label_field` (string) - `latitude_field` (string) - `longitude_field` (string) - `map_session_id` - `metric_fields` - `min_confidence` (number) - `point_layer` (string) - `region_hint` - `rows` - `search_fields` - `ts` - `ts_handle` - `use_cache` (boolean) - `visit_frequency_field` - `workload_fields` ### `request_account_upload` (~714 tokens) Request Account Upload [Tier 2 — Data Intake helper] When: you have account/location rows or an account CSV that you cannot inline in a single ingest_accounts call (e.g. a large CSV, hundreds/thousands of rows). Stage the rows here in one or more chunks, then call ingest_accounts(accounts_handle=...). If the file includes metric, workload, visit-frequency, or dwell-time fields, stage the file here first, inspect returned csv_headers / row keys, confirm role candidates, then pass metric_fields/workload_fields/visit_frequency_field/dwell_time_field to ingest_accounts. Continue only after ingest_accounts has loaded the points. WAYS TO STAGE (all return an upload_handle): (A) CSV on disk + a shell with network (Cursor, Claude Code, Codex, CLI agents): call with no rows to get result.upload_url, then run result.curl_example — POST the raw file with Content-Type: text/csv. No API key: upload_url is the credential (expires in 15 min; each POST appends to the same handle). Fastest for large files; do not re-type rows into csv_text or rows chunks. (B) MCP csv_file: pass the uploaded CSV as a ChatGPT/OpenAI file parameter when available. (C) MCP csv_text: pass csv_text= (whole file in one call, up to 16 MB) when you have no shell or no network. Preserve multiline newlines — do NOT JSON-encode with PowerShell ConvertTo-Json (that corrupts rows into a single line). Use Python json.dumps or MCP csv_file instead. (D) MCP rows: call with rows=; append more with upload_handle=. A local path in csv_file fails (UNREADABLE_FILE_REFERENCE); use (A). Every result carries a fresh upload_url for its handle; an expired URL returns UPLOAD_TOKEN_EXPIRED — call again with upload_handle for a new one. Then: ingest_accounts(accounts_handle=, map_session_id=, label_field=