get_map_visualization

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

Parameters11

ts	any	optional
mode	string	optional
active_tal_id	any	optional
presentation	any	optional
expiry_seconds	any	optional
interaction_flags	any	optional
job_id	any	optional
ts_handle	any	optional
user_id	any	optional
new_project	boolean	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "mode": {
      "default": "view",
      "title": "Mode",
      "type": "string"
    },
    "active_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Active Tal Id"
    },
    "presentation": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Presentation"
    },
    "expiry_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expiry Seconds"
    },
    "interaction_flags": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Interaction Flags"
    },
    "job_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Job Id"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "User Id"
    },
    "new_project": {
      "default": false,
      "title": "New Project",
      "type": "boolean"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "get_map_visualizationArguments"
}

get_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) and result.guidance_handle (the rotating code every territory/map tool requires). 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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "get_guidanceArguments"
}

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

Parameters2

user_request	string	required
context	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "user_request": {
      "title": "User Request",
      "type": "string"
    },
    "context": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Context"
    }
  },
  "required": [
    "user_request"
  ],
  "title": "discover_intentArguments"
}

workflow_advisor

[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` (the EMEP atom inlined as {uri, title, excerpt, truncated} — no resources/read needed); enforces mc_first, viewer_before_compute, build_after_ingest, and conditional analysis_freshness (realign only queues Analyze when a point layer exists or analysis_requested=true). Call it again after each completed step with updated state until done. Other categories (delegate, manual_selection, analyze_present, ...) return a discover_intent/guidance fallback. Scenarios: AB-016, ACB-003, DB-001, WI-001, WI-002, wrong-build-tool, build-before-ingest.

Parameters3

intent_category	string	required
state	any	optional
inputs	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "intent_category": {
      "title": "Intent Category",
      "type": "string"
    },
    "state": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "State"
    },
    "inputs": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Inputs"
    }
  },
  "required": [
    "intent_category"
  ],
  "title": "workflow_advisorArguments"
}

ep_search

[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'.

Parameters4

query	string	required
type	any	optional
tags	any	optional
max_results	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "title": "Query",
      "type": "string"
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Type"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "max_results": {
      "default": 6,
      "title": "Max Results",
      "type": "integer"
    }
  },
  "required": [
    "query"
  ],
  "title": "ep_searchArguments"
}

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

Parameters1

type

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Type"
    }
  },
  "title": "ep_list_topicsArguments"
}

ep_graph_traverse

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

Parameters3

file_path	string	required
depth	integer	optional
edge_kinds	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "file_path": {
      "title": "File Path",
      "type": "string"
    },
    "depth": {
      "default": 1,
      "title": "Depth",
      "type": "integer"
    },
    "edge_kinds": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Edge Kinds"
    }
  },
  "required": [
    "file_path"
  ],
  "title": "ep_graph_traverseArguments"
}

ensure_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. Scenarios: MV-001, I-1.

Parameters4

map_session_id	string	required
wait_seconds	number	optional
poll_interval_ms	integer	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "map_session_id": {
      "title": "Map Session Id",
      "type": "string"
    },
    "wait_seconds": {
      "default": 0,
      "title": "Wait Seconds",
      "type": "number"
    },
    "poll_interval_ms": {
      "default": 500,
      "title": "Poll Interval Ms",
      "type": "integer"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "map_session_id"
  ],
  "title": "ensure_map_viewerArguments"
}

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.

Parameters15

user_goal	string	required
what_happened	string	required
category	any	optional
severity	any	optional
expected_capability	any	optional
suggested_improvement	any	optional
related_tool	any	optional
related_product_area	any	optional
confidence	any	optional
include_context	boolean	optional
context_summary	any	optional
client_name	any	optional
client_version	any	optional
session_id	any	optional
correlation_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "user_goal": {
      "title": "User Goal",
      "type": "string"
    },
    "what_happened": {
      "title": "What Happened",
      "type": "string"
    },
    "category": {
      "$ref": "#/$defs/FeedbackCategoryParam",
      "default": "other"
    },
    "severity": {
      "$ref": "#/$defs/FeedbackSeverityParam",
      "default": "medium"
    },
    "expected_capability": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Capability"
    },
    "suggested_improvement": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Suggested Improvement"
    },
    "related_tool": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Related Tool"
    },
    "related_product_area": {
      "anyOf": [
        {
          "$ref": "#/$defs/FeedbackProductAreaParam"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "confidence": {
      "$ref": "#/$defs/FeedbackConfidenceParam",
      "default": "medium"
    },
    "include_context": {
      "default": false,
      "title": "Include Context",
      "type": "boolean"
    },
    "context_summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Context Summary"
    },
    "client_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Client Name"
    },
    "client_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Client Version"
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Session Id"
    },
    "correlation_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Correlation Id"
    }
  },
  "required": [
    "user_goal",
    "what_happened"
  ],
  "$defs": {
    "FeedbackCategoryParam": {
      "enum": [
        "product_gap",
        "mcp_tool_gap",
        "documentation_gap",
        "data_issue",
        "workflow_confusion",
        "bug",
        "suggestion",
        "other"
      ],
      "type": "string"
    },
    "FeedbackConfidenceParam": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string"
    },
    "FeedbackProductAreaParam": {
      "enum": [
        "territory_planning",
        "alignment",
        "mapping",
        "routing",
        "powerbi",
        "d365",
        "data_import",
        "geocoding",
        "map_component",
        "mcp",
        "other"
      ],
      "type": "string"
    },
    "FeedbackSeverityParam": {
      "enum": [
        "low",
        "medium",
        "high",
        "blocking"
      ],
      "type": "string"
    }
  },
  "title": "submit_feedbackArguments"
}

query_parts

[Tier 2 — Part Metadata] When: enrich or filter parts before build, or inspect attributes without geometry. Prerequisites: part_layer from ezt://part-layers. Next: direct_build, configure_map, or agent-side join before build. Scenarios: DS-002. Returns part_id and attributes only; no geometry.

Parameters6

part_layer	string	required
filter	any	optional
part_ids	any	optional
page_token	any	optional
max_results	integer	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "part_layer": {
      "title": "Part Layer",
      "type": "string"
    },
    "filter": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Filter"
    },
    "part_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Ids"
    },
    "page_token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Page Token"
    },
    "max_results": {
      "default": 100,
      "title": "Max Results",
      "type": "integer"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "part_layer"
  ],
  "title": "query_partsArguments"
}

direct_build

[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 POST /assignments/upload or request_assignment_upload — after parsing rows or passing csv_text/csv_file. 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.

Parameters13

part_layer	string	required
tal_label	string	required
assignments	any	optional
assignments_handle	any	optional
ts	any	optional
ts_handle	any	optional
tal_id	any	optional
expected_revision	any	optional
repair_policy	string	optional
missing_part_policy	string	optional
duplicate_part_policy	string	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "part_layer": {
      "title": "Part Layer",
      "type": "string"
    },
    "tal_label": {
      "title": "Tal Label",
      "type": "string"
    },
    "assignments": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Assignments"
    },
    "assignments_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Assignments Handle"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Id"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "missing_part_policy": {
      "default": "fail",
      "title": "Missing Part Policy",
      "type": "string"
    },
    "duplicate_part_policy": {
      "default": "keep_first",
      "title": "Duplicate Part Policy",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "part_layer",
    "tal_label"
  ],
  "title": "direct_buildArguments"
}

auto_build

[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=<open MC>. 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 both. Modern clients that negotiate protocol >= 2026-07-28 and declare form elicitation may answer missing sizing/dwell (and optional balance) in-band via Resolve/Elicit; legacy/Cursor hosts without form elicitation keep CLARIFICATION_REQUIRED / ask_user (HITL-025 — not a server failure). build_mode may be omitted when elicitation can fill it. Workload is drive time plus dwell — not Revenue or any metric column. When the user says 'balanced on workload' or 'workload-balanced', use workload_bias=100 with no objective.metric; do not ask which metric column workload means — ask dwell (Q5) only. Confirm balance dimension (Q2) and bias (Q3) with the user when unclear — a workload-hour target is sizing, not permission to silently set workload_bias=100 unless workload is already named as the balance dimension. Declare metric_fields at ingest but ask which column (if any) to balance on before auto_build when the user did not already choose workload balance. After build completes: analyze with map_session_id and analysis_panel=single (or load_analysis_panel) so stats appear in the MC dock — not chat-only. Part scope defaults to bbox_intersect (ZIPs intersecting the account-point bbox) — geographic proximity, not state/attribute scope. When the user names a state or region ('TX ZIPs only', 'Texas only'), pass part_scope=explicit and part_filter={state_abbr: TX} immediately; do not default to bbox_intersect (can pull tens of thousands of national ZIPs) and do not query_parts first for an obvious state filter. Scope fields are top-level part_filter/part_ids — never under objective. A genuinely nationwide ZIP request remains supported: when bbox_intersect resolves at national scale, the job continues at full ZIP-level quality and returns a NATIONAL_PART_SCOPE warning rather than silently switching geography. Long partitions publish named 35–42% subphases (travel cache, power solve, border refinement, compactness, seam polish) and renew their worker lease independently; keep polling via next_action/sleep_ms and do not infer a stall from one long quality pass. Prerequisites:

Parameters18

point_layer	string	required
part_layer	string	required
tal_label	string	required
build_mode	any	optional
ts	any	optional
ts_handle	any	optional
expected_revision	any	optional
objective	any	optional
dwell_time	any	optional
visit_frequency_field	any	optional
ignore_visit_frequency	any	optional
part_scope	any	optional
part_ids	any	optional
part_filter	any	optional
repair_policy	string	optional
output_mode	string	optional	tal is the default. assignments returns assignments_artifact plus an authenticated download_url; no ts_handle, tal_id, or map_refresh.
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "point_layer": {
      "title": "Point Layer",
      "type": "string"
    },
    "part_layer": {
      "title": "Part Layer",
      "type": "string"
    },
    "tal_label": {
      "title": "Tal Label",
      "type": "string"
    },
    "build_mode": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Build Mode"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "objective": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Objective"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "ignore_visit_frequency": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ignore Visit Frequency"
    },
    "part_scope": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Scope"
    },
    "part_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Ids"
    },
    "part_filter": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Filter"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "output_mode": {
      "default": "tal",
      "description": "tal is the default. assignments returns assignments_artifact plus an authenticated download_url; no ts_handle, tal_id, or map_refresh.",
      "enum": [
        "tal",
        "assignments"
      ],
      "title": "Output Mode",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "point_layer",
    "part_layer",
    "tal_label"
  ],
  "title": "auto_buildArguments"
}

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=<that layer>. It must be a SECOND ingested point layer, not point_layer. Each seed anchors exactly ONE group, so the seed count must match the group count (fixed_workload_target must derive that same count) or the call fails INVALID_REQUEST with blocked_by=seed_count_mismatch. seed_attraction (0-100, default 70) controls the hold on each group centroid: 100 pins it at its seed, 0 lets the seeds pick only the starting points and the solver drift to the workload centroid. Groups stay workload/metric balanced either way — seeds carry NO workload and are never members of the group they anchor. Both layers receive the same group_field value and the same per-group color, so a technician home paints in its group's color; read result.seed_summary.groups for each pairing plus seed_to_centroid_km. Example — 10 technician homes anchor 10 workload-balanced account groups: point_layer=accounts, seed_point_layer=technician_homes, seed_attraction=100, build_mode={mode: fixed_territory_count, territory_count: 10}. This tool does not spatially join points to parts and does not produce a TAL. Use auto_build for territories. Follow the returned task. The result lists groups (group_id, point_count, workload_hours, point_ids). Full atom: ezt://guidance/workflows/cluster-points. Scenarios: CP-001..005.

Parameters16

point_layer	string	required
build_mode	any	optional
ts	any	optional
ts_handle	any	optional
expected_revision	any	optional
objective	any	optional
dwell_time	any	optional
visit_frequency_field	any	optional
metric_fields	any	optional
group_field	string	optional
group_label_prefix	string	optional
seed_point_layer	any	optional
seed_attraction	any	optional
point_filter	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "point_layer": {
      "title": "Point Layer",
      "type": "string"
    },
    "build_mode": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Build Mode"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "objective": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Objective"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "metric_fields": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metric Fields"
    },
    "group_field": {
      "default": "group_id",
      "title": "Group Field",
      "type": "string"
    },
    "group_label_prefix": {
      "default": "Group",
      "title": "Group Label Prefix",
      "type": "string"
    },
    "seed_point_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Seed Point Layer"
    },
    "seed_attraction": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Seed Attraction"
    },
    "point_filter": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Filter"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "point_layer"
  ],
  "title": "cluster_pointsArguments"
}

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 the visits layer filtered to one bucket_id to drive that day. Full atom: ezt://guidance/workflows/periodic-visit-schedule. Scenarios: PS-001..PS-008.

Parameters18

point_layer	string	required
visit_frequency_field	string	required
dwell_time	any	optional
daily_capacity	any	optional
schedule_label	any	optional
frequency_unit	string	optional
never_visit_values	any	optional
horizon	any	optional
max_buckets_per_day	any	optional
objective	any	optional
cadence_flexibility_pct	any	optional
emit_visit_layer	boolean	optional
visit_layer_name	any	optional
ts	any	optional
ts_handle	any	optional
expected_revision	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "point_layer": {
      "title": "Point Layer",
      "type": "string"
    },
    "visit_frequency_field": {
      "title": "Visit Frequency Field",
      "type": "string"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "daily_capacity": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Daily Capacity"
    },
    "schedule_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Schedule Label"
    },
    "frequency_unit": {
      "default": "interval_days",
      "title": "Frequency Unit",
      "type": "string"
    },
    "never_visit_values": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Never Visit Values"
    },
    "horizon": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Horizon"
    },
    "max_buckets_per_day": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Buckets Per Day"
    },
    "objective": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Objective"
    },
    "cadence_flexibility_pct": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cadence Flexibility Pct"
    },
    "emit_visit_layer": {
      "default": true,
      "title": "Emit Visit Layer",
      "type": "boolean"
    },
    "visit_layer_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Layer Name"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "point_layer",
    "visit_frequency_field"
  ],
  "title": "schedule_visitsArguments"
}

account_build

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

Parameters17

point_layer	string	required
grouping_field	any	optional
part_layer	any	optional
tal_label	any	optional
ts	any	optional
ts_handle	any	optional
expected_revision	any	optional
conflict_policy	string	optional
part_scope	any	optional
part_ids	any	optional
part_filter	any	optional
repair_policy	string	optional
output_mode	string	optional	tal is the default. assignments returns assignments_artifact plus an authenticated download_url; no ts_handle, tal_id, or map_refresh.
visit_frequency_field	any	optional
ignore_visit_frequency	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "point_layer": {
      "title": "Point Layer",
      "type": "string"
    },
    "grouping_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Grouping Field"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Label"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "conflict_policy": {
      "default": "plurality_account_count",
      "title": "Conflict Policy",
      "type": "string"
    },
    "part_scope": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Scope"
    },
    "part_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Ids"
    },
    "part_filter": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Filter"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "output_mode": {
      "default": "tal",
      "description": "tal is the default. assignments returns assignments_artifact plus an authenticated download_url; no ts_handle, tal_id, or map_refresh.",
      "enum": [
        "tal",
        "assignments"
      ],
      "title": "Output Mode",
      "type": "string"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "ignore_visit_frequency": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ignore Visit Frequency"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "point_layer"
  ],
  "title": "account_buildArguments"
}

realign

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

Parameters12

tal_id	string	required
moves	any	optional
ts	any	optional
ts_handle	any	optional
part_layer	any	optional
expected_revision	any	optional
repair_policy	string	optional
map_session_id	any	optional
realign_operation	any	optional
part_ids	any	optional
remove_empty_territories	boolean	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tal_id": {
      "title": "Tal Id",
      "type": "string"
    },
    "moves": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Moves"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "realign_operation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Realign Operation"
    },
    "part_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Ids"
    },
    "remove_empty_territories": {
      "default": false,
      "title": "Remove Empty Territories",
      "type": "boolean"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "tal_id"
  ],
  "title": "realignArguments"
}

delete_tal

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

Parameters4

tal_id	string	required
map_session_id	any	optional
ts_handle	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tal_id": {
      "title": "Tal Id",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "tal_id"
  ],
  "title": "delete_talArguments"
}

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

Parameters9

tal_id	string	required
territory_id	string	required
ts	any	optional
ts_handle	any	optional
part_layer	any	optional
expected_revision	any	optional
repair_policy	string	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tal_id": {
      "title": "Tal Id",
      "type": "string"
    },
    "territory_id": {
      "title": "Territory Id",
      "type": "string"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "tal_id",
    "territory_id"
  ],
  "title": "delete_territoryArguments"
}

territory_split

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

Parameters16

source_tal_id	any	optional
target_territory_id	any	optional
new_territory_label	any	optional
ts	any	optional
ts_handle	any	optional
part_layer	any	optional
point_layer	any	optional
objective	any	optional
dwell_time	any	optional
visit_frequency_field	any	optional
disruption_weight	any	optional
balance_tolerance	any	optional
new_tal_label	any	optional
repair_policy	string	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "source_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source Tal Id"
    },
    "target_territory_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Territory Id"
    },
    "new_territory_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "New Territory Label"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "point_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layer"
    },
    "objective": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Objective"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "disruption_weight": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Disruption Weight"
    },
    "balance_tolerance": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Balance Tolerance"
    },
    "new_tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "New Tal Label"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "territory_splitArguments"
}

territory_merge

[Tier 1 — Minimal-Disruption Merge] When: merge two adjacent territories and rebalance with minimal disruption. 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..004, EV-001.

Parameters16

source_tal_id	any	optional
territory_id_a	any	optional
territory_id_b	any	optional
ts	any	optional
ts_handle	any	optional
part_layer	any	optional
point_layer	any	optional
objective	any	optional
dwell_time	any	optional
visit_frequency_field	any	optional
disruption_weight	any	optional
balance_tolerance	any	optional
new_tal_label	any	optional
repair_policy	string	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "source_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source Tal Id"
    },
    "territory_id_a": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Territory Id A"
    },
    "territory_id_b": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Territory Id B"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "point_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layer"
    },
    "objective": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Objective"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "disruption_weight": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Disruption Weight"
    },
    "balance_tolerance": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Balance Tolerance"
    },
    "new_tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "New Tal Label"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "territory_mergeArguments"
}

territory_rebalance

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

Parameters14

source_tal_id	any	optional
ts	any	optional
ts_handle	any	optional
part_layer	any	optional
point_layer	any	optional
objective	any	optional
dwell_time	any	optional
visit_frequency_field	any	optional
disruption_weight	any	optional
balance_tolerance	any	optional
new_tal_label	any	optional
repair_policy	string	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "source_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source Tal Id"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "point_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layer"
    },
    "objective": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Objective"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "disruption_weight": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Disruption Weight"
    },
    "balance_tolerance": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Balance Tolerance"
    },
    "new_tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "New Tal Label"
    },
    "repair_policy": {
      "default": "default",
      "title": "Repair Policy",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "territory_rebalanceArguments"
}

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

Parameters11

tal_id	string	required
branch_rollup_territory_id	any	optional
branch_territory_path	any	optional
ts	any	optional
ts_handle	any	optional
expected_revision	any	optional
expected_content_hash	any	optional
delegate_ref	any	optional
exclude_locked	boolean	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "tal_id": {
      "title": "Tal Id",
      "type": "string"
    },
    "branch_rollup_territory_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Branch Rollup Territory Id"
    },
    "branch_territory_path": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Branch Territory Path"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "expected_content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Content Hash"
    },
    "delegate_ref": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Delegate Ref"
    },
    "exclude_locked": {
      "default": true,
      "title": "Exclude Locked",
      "type": "boolean"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "tal_id"
  ],
  "title": "extract_tal_branchArguments"
}

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

Parameters9

expected_master_revision	integer	required
branch_metadata	object	required
master_ts	any	optional
master_ts_handle	any	optional
proposal_ts	any	optional
proposal_ts_handle	any	optional
expected_master_content_hash	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "expected_master_revision": {
      "title": "Expected Master Revision",
      "type": "integer"
    },
    "branch_metadata": {
      "additionalProperties": true,
      "title": "Branch Metadata",
      "type": "object"
    },
    "master_ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Master Ts"
    },
    "master_ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Master Ts Handle"
    },
    "proposal_ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Proposal Ts"
    },
    "proposal_ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Proposal Ts Handle"
    },
    "expected_master_content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Master Content Hash"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "expected_master_revision",
    "branch_metadata"
  ],
  "title": "reintegrate_branchArguments"
}

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.

Parameters12

part_layer	string	required
purpose	string	optional
prompt	any	optional
ts	any	optional
active_tal_id	any	optional
destination_territory_id	any	optional
user_id	any	optional
expiry_seconds	any	optional
realign_operation	any	optional
new_territory	any	optional
remove_empty_territories	boolean	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "part_layer": {
      "title": "Part Layer",
      "type": "string"
    },
    "purpose": {
      "default": "generic",
      "title": "Purpose",
      "type": "string"
    },
    "prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Prompt"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "active_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Active Tal Id"
    },
    "destination_territory_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Destination Territory Id"
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "User Id"
    },
    "expiry_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expiry Seconds"
    },
    "realign_operation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Realign Operation"
    },
    "new_territory": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "New Territory"
    },
    "remove_empty_territories": {
      "default": false,
      "title": "Remove Empty Territories",
      "type": "boolean"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "part_layer"
  ],
  "title": "request_part_selectionArguments"
}

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.

Parameters2

selection_task_id	string	required
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "selection_task_id": {
      "title": "Selection Task Id",
      "type": "string"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "selection_task_id"
  ],
  "title": "get_part_selectionArguments"
}

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=<this job>). 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-012.

Parameters10

part_layer	string	required
part_ids	array	required
territory_name	string	required
territory_path	any	optional
tal_id	any	optional
conflict_policy	any	optional
ts	any	optional
map_session_id	any	optional
dwell_time	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "part_layer": {
      "title": "Part Layer",
      "type": "string"
    },
    "part_ids": {
      "items": {
        "type": "string"
      },
      "title": "Part Ids",
      "type": "array"
    },
    "territory_name": {
      "title": "Territory Name",
      "type": "string"
    },
    "territory_path": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Territory Path"
    },
    "tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Id"
    },
    "conflict_policy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Conflict Policy"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "part_layer",
    "part_ids",
    "territory_name"
  ],
  "title": "create_territory_from_partsArguments"
}

analyze

[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). 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 <metric> 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 total_workload_hours column, workload_total null) — never drive-only hours. The result then carries workload_omitted {tal_ids, ask_user, retry}: report the statistics FIRST, then relay ask_user verbatim (it asks for an average onsite/dwell time). Re-run analyze with dwell_time only if the user answers; never invent a default (including 30 minutes). Do not ask for dwell before the first analyze just to avoid the note. Prefer analysis_panel=single with map_session_id so the MC dock fills on this call — that is the one-shot post-build path. The completed result then has analysis_panel.status=pushed, and session state has analysis_panel.loaded=true. phase_timings_ms.panel_push is only a duration, not proof the dock opened. Otherwise pass the full Analyze result (or its task_id) to load_analysis_panel. WORKLOAD UNITS: territories[].workload_total is minutes (workload_unit=minutes). Quote hours only from territory_metric_grids cell total_workload_hours.value. When metrics is omitted and dwell resolves, balance_scores includes workload plus declared metrics — not a location-match score. DOCK HIDE: minimizing the table leaves analysis_panel.loaded true; do not call load_analysis_panel again just to restore it. A new analysis_panel_loaded event opens the dock. Chat-only JSON is not completion when a map is open. Use ezt://guidance/analysis-presentation for narrative. Full atom: ezt://guidance/workflows/analyze-and-present. Scenarios: AN-001..007, MC-009, S002.

Parameters15

ts	any	optional
ts_handle	any	optional
job_id	any	optional
tal_ids	any	optional
part_layer	any	optional
metrics	any	optional
scope	any	optional
compare_tals	boolean	optional
hypothetical_moves	any	optional
max_depth	any	optional
analysis_panel	any	optional
map_session_id	any	optional
dwell_time	any	optional
visit_frequency_field	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "job_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Job Id"
    },
    "tal_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Ids"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "metrics": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metrics"
    },
    "scope": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scope"
    },
    "compare_tals": {
      "default": false,
      "title": "Compare Tals",
      "type": "boolean"
    },
    "hypothetical_moves": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hypothetical Moves"
    },
    "max_depth": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Depth"
    },
    "analysis_panel": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Analysis Panel"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "analyzeArguments"
}

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, label, and declared fields. Also declare grouping_fields (columns for account_build grouping), display_fields (columns shown in map callouts), and search_fields (columns searched in the MC) — undeclared columns are discarded at ingest and later operations on them fail with UNDECLARED_FIELD. NEVER pass a client file path in rows or accounts_handle — the server cannot read /mnt/data/... or other sandbox paths. LARGE FILES: parse the CSV client-side, then call request_account_upload(rows=<chunk> OR csv_text=<raw CSV>) (append via upload_handle), then call this tool with accounts_handle instead of rows. TO SHOW THE POINTS ON AN OPEN MAP: pass map_session_id (the open MC's session id from get_map_visualization / the map_url) — the server pushes the new point layer to that map on completion. WITHOUT map_session_id the points land in a DETACHED TS: read the job result (result_resource_uri) for result.ts_handle and result.map_binding, then bind via show_map_overlay / configure_map / get_map_visualization with that ts_handle. ASYNC COMPLETION IS MANDATORY: the submission/geocoding phase is not workflow completion. Follow the returned Tasks do_this_next and sleep_ms until status=completed, then call the indicated result operation once and inspect the terminal one-liner field, viewer_outcome, failed_rows, map_binding, and map_refresh. viewer_outcome.status painted (or sent_unconfirmed with notified=true) means the linked MC got the push; queued_no_viewer means map_refresh.status=viewer_disconnected (or no viewer yet) — follow recovery.args (ensure_map_viewer); needs_show_map_overlay / rebind_required / detached include literal recovery.args. Do not stop until the binding matches the requested map_session_id, map_refresh.notified=true, and the point layer is visible in the already-open MC (or the detached ts_handle is bound). A linked points-only ingest lands on the surrogate __points__ TAL — that is success (map_refresh.status is sent_unconfirmed or applied); do NOT rebind via get_map_visualization(job_id=...) when notified=true and active_tal_id=__points__. MULTI-OVERLAY CO

Parameters25

rows	any	optional
accounts_handle	any	optional
point_layer	string	optional
label	string	optional
label_field	string	optional
latitude_field	string	optional
longitude_field	string	optional
id_field	string	optional
ts	any	optional
ts_handle	any	optional
country_hint	any	optional
region_hint	any	optional
min_confidence	number	optional
force_regeocode	boolean	optional
use_cache	boolean	optional
accept_suboptimal_geocodes	boolean	optional
metric_fields	any	optional
workload_fields	any	optional
visit_frequency_field	any	optional
dwell_time_field	any	optional
grouping_fields	any	optional
display_fields	any	optional
search_fields	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "rows": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Rows"
    },
    "accounts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Accounts Handle"
    },
    "point_layer": {
      "default": "accounts",
      "title": "Point Layer",
      "type": "string"
    },
    "label": {
      "default": "Accounts",
      "title": "Label",
      "type": "string"
    },
    "label_field": {
      "default": "label",
      "title": "Label Field",
      "type": "string"
    },
    "latitude_field": {
      "default": "latitude",
      "title": "Latitude Field",
      "type": "string"
    },
    "longitude_field": {
      "default": "longitude",
      "title": "Longitude Field",
      "type": "string"
    },
    "id_field": {
      "default": "row_id",
      "title": "Id Field",
      "type": "string"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "country_hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Country Hint"
    },
    "region_hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Region Hint"
    },
    "min_confidence": {
      "default": 0,
      "title": "Min Confidence",
      "type": "number"
    },
    "force_regeocode": {
      "default": false,
      "title": "Force Regeocode",
      "type": "boolean"
    },
    "use_cache": {
      "default": true,
      "title": "Use Cache",
      "type": "boolean"
    },
    "accept_suboptimal_geocodes": {
      "default": true,
      "title": "Accept Suboptimal Geocodes",
      "type": "boolean"
    },
    "metric_fields": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metric Fields"
    },
    "workload_fields": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workload Fields"
    },
    "visit_frequency_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Visit Frequency Field"
    },
    "dwell_time_field": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time Field"
    },
    "grouping_fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Grouping Fields"
    },
    "display_fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Display Fields"
    },
    "search_fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Search Fields"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "ingest_accountsArguments"
}

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. FOUR WAYS TO STAGE (all return an upload_handle): (A) MCP csv_file: pass the uploaded CSV as a ChatGPT/OpenAI file parameter when available. (B) MCP csv_text: pass csv_text=<raw CSV string> when file params are unavailable. 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. (C) MCP rows: call with rows=<chunk>; append more with upload_handle=<prior handle>. (D) HTTP: call with no rows/csv_text to get result.upload_url, then POST rows or csv_text/csv_file. Then: ingest_accounts(accounts_handle=<upload_handle>, map_session_id=<MC session id>, label_field=<label field>). GIS coordinate headers latitude/lat/LAT and longitude/lon/lng/long/LON passthrough case-insensitively. CRM headers such as Address 1: Latitude and Address 1: Longitude are coordinates too — the sheet stays accounts when Region and Territory are also present. suggested_ingest.args sets latitude_field and longitude_field for those headers; pass them through and do not rename them. If 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 — never wait on national geocode. id_field only when a unique business key exists — never label/name; omit otherwise (server synthesizes row-N). On success the result includes suggested_ingest ({tool, args, confidence, notes, geocode_plan}) — prefer those args for the next ingest_accounts call (fill map_session_id from the open MC). geocode_plan states coordinate_fields_detected, will_geocode, eta_class, and passthrough_likely before you submit. Handle is single-use (claimed by the ingest job) and expires (default 1h). Scenarios: IA-001..005, S003.

Parameters6

rows	any	optional
csv_text	any	optional
csv_file	any	optional
upload_handle	any	optional
ttl_seconds	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "rows": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Rows"
    },
    "csv_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Csv Text"
    },
    "csv_file": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Csv File"
    },
    "upload_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Upload Handle"
    },
    "ttl_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ttl Seconds"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "request_account_uploadArguments"
}

request_assignment_upload

[Tier 2 — Direct Build intake] When: you have part-to-territory assignment rows or a legacy spreadsheet (e.g. Zip2Terr.csv with Postal Code + Territory/Region/Division) that you cannot inline in direct_build. Stage rows here, then call direct_build(assignments_handle=<upload_handle>). FOUR WAYS TO STAGE (all return upload_handle): (A) MCP csv_file: pass the uploaded CSV as a ChatGPT/OpenAI file parameter. (B) MCP csv_text: pass csv_text=<raw multiline CSV> — preserve newlines; do NOT JSON-encode with PowerShell ConvertTo-Json (corrupts rows). (C) MCP assignments: pass assignments=<chunk of row objects>; append with upload_handle. (D) HTTP POST /assignments/upload with assignments, csv_text, or csv_file. Legacy columns (Postal Code, Territory, Region, Division) auto-map to part_id + territory_path. Then: direct_build(assignments_handle=<handle>, part_layer=..., tal_label=..., map_session_id=...). Handle is single-use and expires (default 1h).

Parameters6

assignments	any	optional
csv_text	any	optional
csv_file	any	optional
upload_handle	any	optional
ttl_seconds	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "assignments": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Assignments"
    },
    "csv_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Csv Text"
    },
    "csv_file": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Csv File"
    },
    "upload_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Upload Handle"
    },
    "ttl_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ttl Seconds"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "request_assignment_uploadArguments"
}

geocode_address

[Tier 1 — Geocode Only] When: geocode addresses without full account ingest, or headless bulk geocode (GC-001). Prerequisites: none for headless; ts_handle + MC-first when human verifies on map. Prefer ingest_accounts for territory builds (it geocodes inline with accept_suboptimal_geocodes default true). Use this tool when the user must verify geocode quality first; set accept_suboptimal_geocodes=true to accept ZIP-centroid/suboptimal matches. Address columns: address/address_line1/street, city, state, postal (CRM headers auto-mapped). QUOTA: billable provider calls are capped per API key per calendar month. Cache hits cost nothing and are never counted, so never set use_cache=false or force_regeocode=true to work around a cap — that turns free hits into paid calls. Past the cap the tool returns PROVIDER_QUOTA_EXCEEDED carrying limit, used, remaining, and period_resets_at; an operator must raise the cap, so report those numbers instead of retrying or splitting the batch. Next: pass result.geocoded_rows to ingest_accounts or export point layer. Scenarios: GC-001..006.

Parameters9

rows	array	required
country_hint	any	optional
region_hint	any	optional
min_confidence	number	optional
force_regeocode	boolean	optional
use_cache	boolean	optional
accept_suboptimal_geocodes	boolean	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "rows": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Rows",
      "type": "array"
    },
    "country_hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Country Hint"
    },
    "region_hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Region Hint"
    },
    "min_confidence": {
      "default": 0,
      "title": "Min Confidence",
      "type": "number"
    },
    "force_regeocode": {
      "default": false,
      "title": "Force Regeocode",
      "type": "boolean"
    },
    "use_cache": {
      "default": true,
      "title": "Use Cache",
      "type": "boolean"
    },
    "accept_suboptimal_geocodes": {
      "default": false,
      "title": "Accept Suboptimal Geocodes",
      "type": "boolean"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "rows"
  ],
  "title": "geocode_addressArguments"
}

calculate_route

[Tier 1 — Routing] When: drive a list of stops in the best sequence — a windshield itinerary, a service run, a delivery sheet (RT-001..RT-008). This tool routes and sequences existing stops; it never creates or rebalances territories. When a visit-frequency column is on the point layer, the word route is ambiguous — confirm the user wants a driving itinerary of those stops, not schedule_visits, before calling this tool. Prerequisites: a TomTom or Azure Maps key on the server; stops referenced by point_layer must already be ingested, or pass inline lat/lon. TERRITORY STOPS: after a TAL is built or analyze linkage runs, account points carry territory_id. Route one territory with stop_sets source.filter.territory_id set to the leaf id from the last build (leaf_territories[].territory_id), not a display label. start is exactly one stop (home, depot, or one point_id). The territory filter belongs on stop_sets, never on start. ORDERED STOP SETS: stop_sets are visited in the order supplied and optimization NEVER moves a stop between sets, which keeps 'start at home, hit the depot, then the day's calls' in the right sequence. Use order='optimize' to let the solver sequence a set, 'as_given' to keep it fixed. group_by_field splits one set into ordered bands on a column value (e.g. route_priority: every 1 precedes every 2, optimized inside each band). ROUTE TYPES: 'circuit' returns to the start; 'tour' finishes at a declared end stop (end is required); 'open_tour' is a one-way run that ends at the last stop the solver picks, never returning to the start. A circuit's stop_count includes that return. analyze_routes charges dwell once per stop, so the start account is charged dwell twice. Cluster and territory workload charge each account once — those hour figures are not this route's hours. Sequencing is solved server-side against straight-line distance, then one provider call returns road distances, durations, and geometry, so reported numbers are always road-accurate. Drive time here is not the territory workload model — auto_build keeps its own. MANY ROUTES ON ONE MAP: each route is stored in the TS under a route_id, so calling this tool again with a NEW route_id ADDS a route (10 Houston routes coexist, each with its own legend row and color). Reusing an EXISTING route_id REPLACES that route in place, which is the way to add or drop a stop: re-route the same route_id with the revised stop list. Never delete and re-add for a stop change, and never omit route_id when you meant to add a second route (an auto-minted id is fine for a one-off). Use delete_route to drop a whole route; per-route workload facts come from analyze_routes, never from analyze. Pass dwell_time when you want route workload recomputable later; it is stored as provenance and never invented. QUOTA: billable provider calls are capped per API key per calendar month, and a long stop list chunked to the vendor waypoint cap costs one call per chunk. A route is all-or-nothing: past the cap it returns PROVIDER_QUOTA_EXCEEDED with limit, used, remaining, and period_resets_at rather than a partial path. An operator must raise the cap, so report those numbers instead of retrying with fewer stops. Async: returns task_id — follow _meta.next_action (sleep_and_poll → consume_result). Pass map_session_id to draw the path and numbered stops on an open map. Full atom: ezt://guidance/workflows/routes-layer. Scenarios: RT-001..RT-011.

Parameters13

route_type	string	required
start	object	required
stop_sets	array	required
end	any	optional
travel_mode	string	optional
depart_at	any	optional
include_geometry	boolean	optional
route_label	any	optional
route_id	any	optional
dwell_time	any	optional
ts_handle	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "route_type": {
      "title": "Route Type",
      "type": "string"
    },
    "start": {
      "additionalProperties": true,
      "title": "Start",
      "type": "object"
    },
    "stop_sets": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Stop Sets",
      "type": "array"
    },
    "end": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "End"
    },
    "travel_mode": {
      "default": "car",
      "title": "Travel Mode",
      "type": "string"
    },
    "depart_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Depart At"
    },
    "include_geometry": {
      "default": true,
      "title": "Include Geometry",
      "type": "boolean"
    },
    "route_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Route Label"
    },
    "route_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Route Id"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "route_type",
    "start",
    "stop_sets"
  ],
  "title": "calculate_routeArguments"
}

isochrone_build

[Tier 1 — Isochrone Build] When: draw the area reachable by DRIVING from one or more origins within a time or distance budget — '20-minute drive-time area around each branch', service area, catchment, coverage ring, reachable range, isochrone, isodistance (IS-001..IS-006). It draws reachable area. It has no objective and does not balance workload. Prerequisites: a TomTom or Azure Maps key on the server (no key → ISOCHRONE_NOT_CONFIGURED, no degraded mode — never substitute a straight-line radius); a part_layer (read ezt://part-layers); and, for point-layer origins, ingested points plus ts_handle or map_session_id. Inline origins need no TS. ORIGINS x BANDS: origins are inline {latitude, longitude, label?} or a point-layer reference {point_layer, point_ids?, filter?, label_field?} — '40 minutes around each of my 6 branches' is ONE call. bands are [{time_budget_seconds} | {distance_budget_meters}], one budget per band, and every band in a call must use the SAME unit (mixing returns MIXED_BUDGET_TYPES). One band → one leaf per origin; several bands → a rollup per origin with one leaf per band. Cost is origins x bands provider calls, capped by TOO_MANY_ORIGINS (default 25) / TOO_MANY_BANDS (default 5). QUOTA: those billable calls also draw on a per-API-key monthly cap. The whole fan-out is claimed before any call goes out, so a build that does not fit returns PROVIDER_QUOTA_EXCEEDED with limit, used, remaining, and period_resets_at having spent nothing. An operator must raise the cap; report those numbers instead of retrying with fewer bands. LIMITS: travel_mode is 'car' or 'truck' ONLY — neither provider offers a walking or cycling reachable range, unlike calculate_route. time_budget_seconds <= 21600, distance_budget_meters <= 500000 (BUDGET_OUT_OF_RANGE). depart_at is supported; arrive_at is not. avoid accepts toll_roads, motorways, ferries, unpaved_roads, carpools, border_crossings, tunnels, car_trains, low_emission_zones. GEOMETRY AND PARTS: each territory stores the provider's exact polygon AND part_ids assigned by centroid_within overlay, so analyze and territory stats work normally while the map shows the true drive-time edge. Bands nest and their polygons overlap on purpose (tightest paints on top); part assignment is disjoint — a part joins the tightest band containing it, then the nearer origin. realign can move parts between bands but NEVER moves a polygon, so a realigned isochrone's assignment intentionally diverges from its drawn shape. A band budget is NOT territory workload and NOT route drive time — never report '20-minute band' as 20 minutes of workload or feed it to auto_build. Async: returns task_id — follow _meta.next_action (sleep_and_poll → consume_result) and sleep the authoritative sleep_ms, never estimated_remaining_ms. Partial provider failure still builds the TAL and reports failed_requests[]. Then: analyze(tal_ids=[<tal_id>], map_session_id, analysis_panel='single') for per-band accounts and metrics. Pass map_session_id here to paint the bands on an open map. Full atom: ezt://guidance/workflows/isochrone-territories. Scenarios: IS-001..IS-006.

Parameters14

origins	array	required
bands	array	required
part_layer	string	required
travel_mode	string	optional
route_type	string	optional
traffic	boolean	optional
depart_at	any	optional
avoid	any	optional
tal_label	any	optional
tal_id	any	optional
part_overlay	string	optional
ts_handle	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "origins": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Origins",
      "type": "array"
    },
    "bands": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Bands",
      "type": "array"
    },
    "part_layer": {
      "title": "Part Layer",
      "type": "string"
    },
    "travel_mode": {
      "default": "car",
      "title": "Travel Mode",
      "type": "string"
    },
    "route_type": {
      "default": "fastest",
      "title": "Route Type",
      "type": "string"
    },
    "traffic": {
      "default": true,
      "title": "Traffic",
      "type": "boolean"
    },
    "depart_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Depart At"
    },
    "avoid": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Avoid"
    },
    "tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Label"
    },
    "tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Id"
    },
    "part_overlay": {
      "default": "centroid_within",
      "title": "Part Overlay",
      "type": "string"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "origins",
    "bands",
    "part_layer"
  ],
  "title": "isochrone_buildArguments"
}

seed_build

[Tier 1 — Seed Build] When: grow ONE territory outward from a seed location until it holds a target number of locations or a target metric sum — 'a franchise territory around this address with 40 stores', 'grow from this point until it reaches $2M revenue', 'the ZIPs around our new branch that cover 300 stores'. The result is an ordinary part-based territory (ZIPs, counties) appended as a new leaf on an existing layer (tal_id) or as a new layer when tal_id is omitted. It grows one territory from one seed. It does not partition, balance, or route. Prerequisites: an ingested point layer (ingest_accounts) — its locations are the values counted or summed; a part_layer (ezt://part-layers); and the seed as {longitude, latitude}. Resolve an address or POI to coordinates first with the address geocoding tool; a map click already gives coordinates. TARGET: target={type: 'location_count', value: N} or {type: 'metric_sum', field: <column declared in metric_fields at ingest>, value: X}. An undeclared field returns UNDECLARED_FIELD — re-ingest with metric_fields. Fit is CLOSEST: growth adds the nearest adjacent part that still fits, then takes the smallest remaining neighbour only when overshooting lands nearer the target than stopping short. target_status reports reached | closest_under | closest_over | frontier_exhausted | max_parts_reached. NO OVERLAP, EVER: with tal_id, parts already in any territory of that layer are never taken — the new territory drifts away from them instead (blocked_part_count, seed_offset_km). A seed inside an existing territory fails SEED_PART_ASSIGNED; pick another seed or reassign parts with realign. There is no allow_overlap flag. SCOPE: growth reads only the seed's neighbourhood — the point layer is indexed once and parts are materialised ring by ring outward from the seed part; it never joins every location to every part, so a national point layer costs the same as a local one. part_filter / part_ids are an ALLOWLIST (parts outside it do not exist for the walk), not a performance prerequisite: pass part_scope='explicit' + part_filter={state_abbr: 'TX'} only when the user wants the territory confined to that state. bbox_intersect / point_matched are accepted and ignored here; the result reports the materialised part count and ring depth the walk touched. ONE SEED PER CALL: for several franchisees call seed_build once per seed with the same tal_id; earlier territories become blocked for later seeds. Async: returns task_id — follow _meta.next_action (sleep_and_poll → consume_result) and sleep the authoritative sleep_ms. The result is handle-only (ts_handle, no inline ts) with created_territory, the grown part ids, target.{requested, achieved, delta}, and do_this_next. Then: analyze(tal_ids=[<tal_id>], map_session_id, analysis_panel='single') so the map dock shows the territory; without dwell Analyze omits workload and returns workload_omitted.ask_user to relay after the stats. Pass map_session_id here to paint the territory on the open map. Full atom: ezt://guidance/workflows/seed-grown-territory. Scenarios: SB-001..SB-004.

Parameters15

seed	object	required
target	object	required
part_layer	any	optional
point_layer	any	optional
tal_id	any	optional
territory_name	any	optional
tal_label	any	optional
part_scope	any	optional
part_filter	any	optional
part_ids	any	optional
max_parts	any	optional
ts_handle	any	optional
map_session_id	any	optional
user_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "seed": {
      "additionalProperties": true,
      "title": "Seed",
      "type": "object"
    },
    "target": {
      "additionalProperties": true,
      "title": "Target",
      "type": "object"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "point_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layer"
    },
    "tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Id"
    },
    "territory_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Territory Name"
    },
    "tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Label"
    },
    "part_scope": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Scope"
    },
    "part_filter": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Filter"
    },
    "part_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Ids"
    },
    "max_parts": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Parts"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "User Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "seed",
    "target"
  ],
  "title": "seed_buildArguments"
}

delete_route

[Tier 2 — Delete Route] When: drop a whole route from the map and the TS (e.g. 'delete the Tuesday A route', 'remove route houston-tue-a'). Prerequisites: map_session_id for an open MC (preferred), else ts_handle; plus route_id (or an exact unique route label). NOT for removing a single stop — for that, call calculate_route again with the SAME route_id and the remaining stops, which replaces the route in place. Already-absent routes return ok with already_absent=true and no error. An ambiguous label returns AMBIGUOUS_ROUTE with matching_route_ids — pass an explicit route_id rather than guessing. Synchronous: no task_id. Verify the open map legend no longer lists the route. Scenarios: RT-010.

Parameters4

route_id	string	required
map_session_id	any	optional
ts_handle	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "route_id": {
      "title": "Route Id",
      "type": "string"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "route_id"
  ],
  "title": "delete_routeArguments"
}

analyze_routes

[Tier 2 — Route Facts] When: you need per-route numbers for routes calculate_route already drew — drive hours, dwell hours, route_workload_hours, stop coordinates, centroid, bbox (e.g. 'which of my Houston runs has room for one more stop', 'total hours for each route'). Prerequisites: at least one route in the session/TS (map_session_id preferred, else ts_handle); dwell confirmed by the user unless calculate_route already stored it. route_workload_hours = provider drive time + confirmed dwell, with NO visit-frequency multiplier. dwell_hours is one dwell per stop in stop_count. A circuit's stop_count includes the return to the start, so that account is charged dwell twice. Cluster and territory workload charge each account once. This is a DIFFERENT quantity from those hours — never sum, compare, or substitute one for the other. FACTS ONLY: no capacity, no headroom, no ranking, no overloaded flag. Apply constraints like 'nearest route under 7 hours' yourself from centroid + route_workload_hours, then add the stop by re-running calculate_route with that route_id and the revised stop list. Anti-patterns: do NOT call analyze for routes (analyze is TAL/part-grained and returns territory workload); do NOT feed these hours into auto_build, territory_rebalance, or a territory workload figure. Unresolved dwell returns CLARIFICATION_REQUIRED / needs_dwell — ask the user, never invent a default (including 30 minutes). Synchronous: no task_id. Scenarios: RT-011.

Parameters5

route_ids	any	optional
map_session_id	any	optional
ts_handle	any	optional
dwell_time	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "route_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Route Ids"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "dwell_time": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dwell Time"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "analyze_routesArguments"
}

tasks_cancel

[Tier 2 — MCP Tasks mirror] Tool-only client equivalent of native tasks/cancel. Use only when this mirror appears in tools/list; Tasks-capable clients use tasks/cancel instead. Prerequisite: task_id from the immediately preceding async submission. Returns the same Task status fields and EZT poll metadata as the native method. Cancellation is cooperative; confirm TS unchanged or partial per the originating tool contract. Scenarios: OP-001.

Parameters1

task_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    }
  },
  "required": [
    "task_id"
  ],
  "title": "tasks_cancelArguments"
}

tasks_get

[Tier 2 — MCP Tasks mirror] Tool-only client equivalent of native tasks/get. Use only when this mirror appears in tools/list; Tasks-capable clients use tasks/get. Prerequisite: task_id from the immediately preceding async submission. Polling never starts work. next_action and sleep_ms sit on this document (the same fields as the submit result) and are repeated under _meta. Follow next_action exactly: sleep_and_poll means sleep the single authoritative sleep_ms value, call tasks_get once, then re-read both fields; consume_result means call tasks_result once now; stop_error means stop. status=cancelled is a user stop — do not resubmit the same tool unless asked. Never sleep on estimated_remaining_ms and never poll HTTP /result for status. While a task is still queued, _meta also carries queue_position (1-based within its worker lane), queue_depth, queue_lane (io|compute), and estimated_start_ms — report these to explain a wait; estimated_start_ms is advisory and never a sleep duration. The result is the same Task status document returned by native tasks/get. Scenarios: OP-002, tool-only MCP clients.

Parameters1

task_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    }
  },
  "required": [
    "task_id"
  ],
  "title": "tasks_getArguments"
}

tasks_result

[Tier 2 — MCP Tasks mirror] Tool-only client equivalent of native tasks/result. Call exactly once after tasks_get returns status=completed and _meta.next_action=consume_result. Prerequisite: task_id from that completed Task. Returns the originating tool's terminal handle-only result (ts_handle, counts, timings, map binding/shortcut); it never returns inline TS when a handle exists. Do not poll this operation while working. After build results, pass ts_handle or the same task_id as job_id to analyze with explicit tal_ids; never resubmit a build to recover from an Analyze lookup error.

Parameters1

task_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    }
  },
  "required": [
    "task_id"
  ],
  "title": "tasks_resultArguments"
}

set_map_state

[Tier 2 — Low-Level MC State] When: switch MC mode, active TAL, or pending job ref, or jump the open MC camera with center ([longitude, latitude]) and/or zoom (0-24). Camera here is session-only and does not write the TS — use configure_map to persist a default view. Prerequisites: map_session_id. Prefer configure_map for durable TS map_config. Prefer request_part_selection for selection workflows. Scenarios: residual backlog (no dedicated scenario by design).

Parameters7

map_session_id	string	required
mode	any	optional
active_tal_id	any	optional
pending_job_reference	any	optional
center	any	optional
zoom	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "map_session_id": {
      "title": "Map Session Id",
      "type": "string"
    },
    "mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode"
    },
    "active_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Active Tal Id"
    },
    "pending_job_reference": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pending Job Reference"
    },
    "center": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Center"
    },
    "zoom": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Zoom"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "map_session_id"
  ],
  "title": "set_map_stateArguments"
}

get_map_selection

[Tier 2 — MC Selection Poll] When: read the latest committed MC session selection — especially when Monica started selection from the legend finger icon and then tells the agent what to do with 'my selection' (no prior request_part_selection in this turn). Prerequisites: map_session_id of the open MC. Returns part_layer + part_ids (+ selection_task_id when a first-class task was created). Prefer get_part_selection when you already have selection_task_id and it is still available. Next for 'add these to <territory>': call realign with tal_id, the same map_session_id, and moves=[{part_id, to_territory_id}] derived from every returned part_id using the stable leaf territory_id (created_territory.territory_id / leaf catalog). Display-name aliases need an exact unique name match — do not invent shorthand (T3 ≠ Territory 3). If unclear, ask which leaf. Do not resend the TS or request a new selection. Scenarios: MC-004 variants, user-initiated select.

Parameters2

map_session_id	string	required
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "map_session_id": {
      "title": "Map Session Id",
      "type": "string"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "map_session_id"
  ],
  "title": "get_map_selectionArguments"
}

load_analysis_panel

[Tier 2 — Analysis Panel Display] When: show Analyze JSON in the MC bottom dock (single or comparison) after a completed analyze that omitted analysis_panel. Prefer analyze(analysis_panel=single, map_session_id=...) so the dock fills without this second call. Prerequisites: map_session_id; a full Analyze result — pass task_id/job_id of the completed analyze job, or analyses=[<full Analyze result>]. The result must include tal_analyses and ts_identity (territory_metric_grids when metrics exist). A thin {tal_analyses} object is INVALID_REQUEST, not an empty dock. presentation_mode is single|compare|executive|diagnostic — territory_metric_grid is default_presentation.view inside the Analyze payload, not a presentation_mode. Does not mutate TS. Re-run analyze after any TAL or point change (I-2). dismiss=true hides the whole dock, header bar included, and keeps the stats on the session. analysis_panel.dismissed is then true. A later analyze with analysis_panel=single shows the dock again. Omit analyses on a dismiss call. Dual surface: the dock renders in the in-chat map on Apps-capable hosts and in the map_url tab everywhere else — same map_session_id, no extra call. Scenarios: MC-009, AN-006, MC-007.

Parameters9

map_session_id	string	required
analyses	any	optional
labels	any	optional
roles	any	optional
presentation_mode	any	optional
task_id	any	optional
job_id	any	optional
dismiss	boolean	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "map_session_id": {
      "title": "Map Session Id",
      "type": "string"
    },
    "analyses": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Analyses"
    },
    "labels": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Labels"
    },
    "roles": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Roles"
    },
    "presentation_mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Presentation Mode"
    },
    "task_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Task Id"
    },
    "job_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Job Id"
    },
    "dismiss": {
      "default": false,
      "title": "Dismiss",
      "type": "boolean"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "map_session_id"
  ],
  "title": "load_analysis_panelArguments"
}

configure_map

[Tier 2 — Durable Map Config] When: set or update project_name (the durable TS short name used as the Map Component heading), loaded_part_layers, active_part_layer, active_tal_id, point_layer_classifications, classification, presentation, center, or zoom on the TS. project_name is first-class: persists to ts.properties.map_config.project_name and emits config_changed so a linked session refreshes the heading in place. POINT SYMBOLOGY: point_layer_classifications is the way to recolor/resize/reshape points on an open map — never export GeoJSON, compute breaks client-side, and repost a TS. Each entry is {point_layer, field, method: quantile|equal_interval|categorical|manual, class_count (2-12), channel: color|size|shape, optional colors/sizes/shapes, optional style:{color,size,opacity,shape} for the layer base symbol}. Supported shapes: circle|square|triangle|diamond|star|cross|house|pin|flag|hexagon|pentagon|shield|arrow_up|building (aliases home→house, marker/map_pin→pin, hex→hexagon, arrow/up→arrow_up, warehouse/depot→building, plus/x→cross). The server computes breaks from the in-session points, writes point_layers[].<channel>_classification, pushes config_changed, and returns the applied classes with per-class counts. Categorical missing values become an Ungrouped class. One classification per channel per layer: a second color entry replaces the first. Two encodings on one layer mix channels (color+size or color+shape). clear:true with point_layer and channel drops that channel classification, including a same-channel classification object. Other channels and the base style stay. active_channels reports the channels still set. Method defaults to quantile for numeric fields and categorical otherwise; pass one entry per layer to give two point layers distinct colors or shapes. classification (without a point_layer) stays a project-level map_config patch and does NOT paint points; a point-layer-targeted classification is routed to symbology with a warning. Optional center ([longitude, latitude]) and zoom (0-24) persist as the TS default camera and jump an open MC when included on this call; Monica's pan is not captured. Prefer map_session_id for an open MC — the live session TS is the patch base; a stale pre-ingest ts_handle must not strip points/part layers. Not the entry tool for browsing a TS — that is get_map_visualization (I-1). Prerequisites: map_session_id, ts_handle, or inline ts; points already ingested before point_layer_classifications; part_layer from ezt://part-layers before builds. Next: build or analyze; if active TAL changes, re-run analyze then load_analysis_panel (I-2). Scenarios: MC-010, MC-012, DS-001, baseline workflow step 4.

Parameters16

map_session_id	any	optional
ts_handle	any	optional
ts	any	optional
project_name	any	optional
loaded_part_layers	any	optional
active_part_layer	any	optional
active_tal_id	any	optional
point_layer_classifications	any	optional
classification	any	optional
presentation	any	optional
center	any	optional
zoom	any	optional
merge_strategy	any	optional
expected_revision	any	optional
expected_content_hash	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "project_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project Name"
    },
    "loaded_part_layers": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Loaded Part Layers"
    },
    "active_part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Active Part Layer"
    },
    "active_tal_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Active Tal Id"
    },
    "point_layer_classifications": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layer Classifications"
    },
    "classification": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Classification"
    },
    "presentation": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Presentation"
    },
    "center": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Center"
    },
    "zoom": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Zoom"
    },
    "merge_strategy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Merge Strategy"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "expected_content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Content Hash"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "configure_mapArguments"
}

show_map_overlay

[Tier 1 — Map Overlay] When: customer wants something on the map — US ZIP codes, counties, accounts/points, or a territory alignment — in any phrasing ('add US zip codes to the map', 'show zip codes', 'add zips'). Prerequisites: ts_handle (or inline ts) from get_map_visualization; viewer connected for live MC refresh. Pass user_request alone (e.g. 'add US zip codes to the map') or overlay_kind (part_layer | point_layer | tal | route) with optional overlay_id. Resolves the four MC overlay families and calls the correct underlying step (configure_map for part layers and active TAL; point layers must already be in the TS from ingest_accounts). Source the TS via ts_handle, inline ts, OR map_session_id (preferred for points: reads the LIVE session TS so points pushed by ingest_accounts(map_session_id=...) are found without threading a new ts_handle). Returns overlay_kind, overlay_id, viewer_hint, and for part layers a visibility block (state, min_zoom, camera_action). An open map_session_id zooms the MC to min_zoom (camera_action=fit_to_visible). When the user already named a center and zoom, do_this_next.tool is configure_map: call it once with that center and zoom before ingest or a point classification, so the fit does not replace it. Skip that call when no center was named, and do not invent one. Do not call configure_map again unless a later result also reports camera_action=fit_to_visible. Do not use ezt_test/focusAt. POINT LAYERS with map_session_id: status=already_on_map is verified against the live session render payload; when the layer is in the TS but missing from the session, the tool pushes a refresh and returns status=refreshed with a map_refresh block — check its render_ack before claiming points are visible. ROUTE overlay (overlay_kind=route) needs map_session_id and only re-shows or hides routes calculate_route already drew — 'hide/remove/clear the route' clears them; with no route yet it returns blocked_by=needs_route pointing at calculate_route. Pass route_id to target ONE of several routes; omit it to act on all of them. To delete a route for good use delete_route; to change a route's stops re-run calculate_route with the same route_id. calculate_route already draws its own result, so this is recovery, not the normal path. Prefer this over raw configure_map for show/add-on-map asks. Part-layer overlays are written onto the live session even when map_push_status=viewer_not_connected (session durability); SSE paint still needs a connected viewer. A later linked ingest_accounts keeps those overlays (non-destructive compose with points). Dual surface: the overlay lands on the in-chat map on Apps-capable hosts and in the map_url tab everywhere else — same map_session_id, no extra call. Scenarios: MC-010, ChatGPT/external MCP.

Parameters11

user_request	any	optional
overlay_kind	any	optional
overlay_id	any	optional
route_id	any	optional
ts_handle	any	optional
ts	any	optional
map_session_id	any	optional
expected_revision	any	optional
expected_content_hash	any	optional
merge_strategy	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "user_request": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "User Request"
    },
    "overlay_kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Overlay Kind"
    },
    "overlay_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Overlay Id"
    },
    "route_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Route Id"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "ts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "expected_revision": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision"
    },
    "expected_content_hash": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Content Hash"
    },
    "merge_strategy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Merge Strategy"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "show_map_overlayArguments"
}

export_geojson

[Tier 2 — Project save] The only Territory Solution export. Materialize the working GeoJSON FeatureCollection (territory polygons with part_ids, point features, and route paths + numbered stops). Omit tal_ids / point_layers / route_layers for the full project. Async: returns task_id; follow its Tasks next_action/sleep_ms until completed, then fetch the result once. The result carries geojson_artifact {artifact_id, bytes}, zip (default true = gzip download), and download_url (GET with Bearer API key) — never an inline multi-MB body. Set zip=false for uncompressed GeoJSON. Prerequisites: ts_handle, completed build job_id, or map_session_id. Set include_points=false or include_routes=false to drop a family. Reopen with import_geojson, then get_map_visualization(ts_handle=...). Paint travels with the export: every feature and point_layers[] / route_layers[] entry carries style {color, opacity, size, shape, weight} exactly as shown, so reopen and Designer import need no restyling. An EasyTerritory Designer rolodex project is this download POSTed to Designer REST/Agent/Projects/FromTerritorySolution (new) or PUT to .../Projects/{projectId}/FromTerritorySolution (update). Territories, points, and routes import. There is no MCP push tool (ezt://guidance/workflows/push-to-designer).

Parameters10

ts_handle	any	optional
job_id	any	optional
map_session_id	any	optional
tal_ids	any	optional
point_layers	any	optional
route_layers	any	optional
include_points	boolean	optional
include_routes	boolean	optional
zip	boolean	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "job_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Job Id"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "tal_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Ids"
    },
    "point_layers": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layers"
    },
    "route_layers": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Route Layers"
    },
    "include_points": {
      "default": true,
      "title": "Include Points",
      "type": "boolean"
    },
    "include_routes": {
      "default": true,
      "title": "Include Routes",
      "type": "boolean"
    },
    "zip": {
      "default": true,
      "title": "Zip",
      "type": "boolean"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "export_geojsonArguments"
}

import_geojson

[Tier 2 — Project reopen] Import a GeoJSON FeatureCollection (standard points or an export_geojson artifact, including gzip/zip). Returns ts_handle + summary — pass ts_handle to get_map_visualization / analyze / export_geojson next; do not repost the GeoJSON body. Arbitrary territory polygons WITHOUT part_ids are rejected (TERRITORY_POLYGONS_WITHOUT_PART_IDS) unless you explicitly pass part_layer plus overlay_policy="centroid_within" to assign parts whose centroids fall inside each polygon. Optional: point_layer (name for imported points), tal_label. Supply geojson (object), geojson_text (JSON or sniffed gzip/zip), or geojson_gzip (base64 gzip/zip). An EasyTerritory Designer rolodex project arrives here too: GET Designer REST/Agent/Projects (list) then GET .../Projects/{projectId}/TerritorySolution with the user's ezt_pat_ Bearer, and pass the (gzipped) file as geojson_gzip. There is no MCP pull tool (ezt://guidance/workflows/pull-from-designer).

Parameters8

geojson	any	optional
geojson_text	any	optional
geojson_gzip	any	optional
point_layer	any	optional
tal_label	any	optional
part_layer	any	optional
overlay_policy	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "geojson": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Geojson"
    },
    "geojson_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Geojson Text"
    },
    "geojson_gzip": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Geojson Gzip"
    },
    "point_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Point Layer"
    },
    "tal_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tal Label"
    },
    "part_layer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Part Layer"
    },
    "overlay_policy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Overlay Policy"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "title": "import_geojsonArguments"
}

ezt

[Tier 1 — Plain-language orchestrator] Use when the exact granular tool is unclear or when a greedy/file-holding client wants to complete an action in one step. Prefer granular tools directly when you know the step. Pass request (your goal) plus optional csv_file / accounts_handle / assignments_handle / map_session_id / ts_handle. For an uploaded CSV, pass csv_file as the ChatGPT/OpenAI file parameter; ezt parses/stages it server-side and can run ingest_accounts with map_session_id so points appear on the open map. For fixed-workload builds, args.target_hours / args.workload_target are normalized to auto_build build_mode.mode=fixed_workload_target. Modern form-capable clients (protocol >= 2026-07-28) may answer missing part_layer, tal_label, sizing, dwell, and optional balance in-band (aligned with auto_build); legacy hosts keep CLARIFICATION_REQUIRED / ask_user (HITL-025).

Parameters9

request	string	required
state_facts	any	optional
args	any	optional
csv_file	any	optional
accounts_handle	any	optional
assignments_handle	any	optional
ts_handle	any	optional
map_session_id	any	optional
guidance_handle	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "request": {
      "title": "Request",
      "type": "string"
    },
    "state_facts": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "State Facts"
    },
    "args": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Args"
    },
    "csv_file": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Csv File"
    },
    "accounts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Accounts Handle"
    },
    "assignments_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Assignments Handle"
    },
    "ts_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ts Handle"
    },
    "map_session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Map Session Id"
    },
    "guidance_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Guidance Handle"
    }
  },
  "required": [
    "request"
  ],
  "title": "eztArguments"
}

AI Easyterritory EZT MCP

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

get_map_visualization

get_guidance

discover_intent

workflow_advisor

ep_search

ep_list_topics

ep_graph_traverse

ensure_map_viewer

submit_feedback

query_parts

direct_build

auto_build

cluster_points

schedule_visits

account_build

realign

delete_tal

delete_territory

territory_split

territory_merge

territory_rebalance

extract_tal_branch

reintegrate_branch

request_part_selection

get_part_selection

create_territory_from_parts

analyze

ingest_accounts

request_account_upload

request_assignment_upload

geocode_address

calculate_route

isochrone_build

seed_build

delete_route

analyze_routes

tasks_cancel

tasks_get

tasks_result

set_map_state

get_map_selection

load_analysis_panel

configure_map

show_map_overlay

export_geojson

import_geojson

ezt

Install

Remote endpoint

Related servers