EasyTerritory MCP

[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_handleComputes fromterritory priorstatistics computefor jobs),one or map_session_id alone to analyze the open map as it ismore nowalignments, including pointsi.e. ingestedhow afterbalanced the build. A job_id or ts_handle is that job's snapshot and wins when bothterritories are passed, except when the snapshot has no points and the open map does: then the live map is analyzed and the result warns ANALYZED_LIVE_SESSION. Prerequisites: TAL exists; re-run after any TAL or point change (I-2)—never treat stale analysis as current. Returns JSON facts and presentation guidance URI; no prose. metrics: omit to analyze all declared point-layer columns, or pass explicit names. System dimensions (always valid, nothow pointalignments columns)compare: workload (territory hours; aliasaccount total_workload_hours)counts, account_count. Point columns must be fields declared atmetric ingesttotals (metric_fields/workload_fields, e.g. Revenue, Units Sold); undeclared columns, areworkload discardedhours, atbalance ingestscores, and fail with UNDECLARED_FIELD — re-ingest with the column declared to analyze it. Responsecross-TAL includescomparison; available_metrics.hypothetical_moves METRICpreviews COLUMNSa ALWAYSrealign. RENDERInput: the territory_metric_gridsmap_session_id (and the MC dock) carry Total Count plus a Total <metric> column for EVERY declared metric_fieldsopen columnmap ofas theit pointis layernow), in declaration orderts_handle, even when metrics names only account_countts, or workload — a count-only panel is never the correct outcome when metrics are declared. Declared names may becompleted barebuild stringsjob_id (Designerpass pull)tal_ids orwhen {field,label,type}several objectsTALs (ingestexist). Metric cells are parsed leniently: '14,651', '$1,200.50', and padded strings sum as numbers. DWELL / WORKLOAD (T-171)metrics: workload hours need onsite/dwell time — requestomit dwell_time,for TALevery build_provenance.dwell_timedeclared (auto_build)column, or the point layer's dwell_time_field. When none resolves, Analyze STILL RUNS and reports counts, metrics, classification breakdowns, and balance on thosename dimensions;them; 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}: reportand theaccount_count statisticsare FIRST,always thenavailable. relayWorkload ask_userneeds verbatimdwell (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 askbuild's forrecorded dwell before the first analyze just to, avoidor the note. DRIVE-TIME TALSlayer's (isochrone_builddwell_time_field): accounts are counted inside; eachwithout providerit polygonthe (measured_by=area_polygon),result inhas every area that containsother themstatistic, so areano totalsworkload, canand exceedworkload_omitted.ask_user, the account count; area_overlaps lists accounts shared across origins. scope and hypothetical_moves doquestion notfor apply.the Preferuser. 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 proofmap's theanalysis dock opened. Otherwise pass the full Analyze result (or its task_idanalysis_panel.status=pushed) to load_analysis_panel. WORKLOAD UNITS:. territories[].workload_total is minutes (workload_unit=minutes). Quoteminutes; 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_loadedare eventin opensterritory_metric_grids. theDrive-time dock.alignments Chat-onlycount JSONaccounts isinside noteach completionpolygon. whenReturns 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.task.

 ⟨7 unchanged words⟩  open map's analysis dock with this result (passneeds map_session_id); prefer it.. comparison_slot fills the same dock (no side-by-side  ⟨44 unchanged words⟩ ],"default":null,"title":"Dwell Time"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"hypothetical_moves":{"anyOf":[{"items ⟨136 unchanged words⟩ 

[Tier 2 — RouteReturns Facts]the When:total youhours needfor per-routeeach numbersof forthe routes calculate_route already drewhas —drawn: drive hours, dwell hours, route_workload_hours, stop coordinates, centroid, bbox (e.g. 'which of my Houston runs has roomprovider fordrive onetime moreplus stop'dwell, 'total hours forno eachvisit-frequency route'multiplier). Prerequisites:, atstop leastcoordinates, onecentroid, routeand inbbox. theSynchronous. session/TSNeeds (map_session_id preferred, elseor ts_handle); dwell confirmed by the user unless calculate_route already stored it. route_workload_hours, =and providerdwell drivefrom timedwell_time +or confirmedthe dwell, with NO visit-frequencyrecorded multiplier.on dwell_hoursthe isroute; oneunresolved dwell per stopreturns inCLARIFICATION_REQUIRED stop_count.(needs_dwell). A circuit's stop_count includes the return to the start, so that account is chargedstop's 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 thecounts other.twice. FACTSFacts ONLYonly: no capacity, no headroom, no ranking, no overloaded flag. Applyor constraintsoverload likeflags. 'nearestThese routehours underare 7a hours'different yourselfmeasure 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,and orcluster aworkload; territory workload figure. Unresolved dwell returns CLARIFICATION_REQUIRED / needs_dwell — ask the user, never invent a default (including 30 minutes). Synchronous: nostatistics task_id.come Scenarios:from RT-011.analyze.

 ⟨10 unchanged words⟩ ":null,"title":"Dwell Time"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨37 unchanged words⟩ 

[Tier 1 — Balanced Territory Builder] When:Partitions partitioningested account points into N balanced territories over a part layer (for example, ten territories; Mode Asales count,territories Modewith Bequal workload target, Scoped Split). Execution gate: after sizing, balance, dwell, and scope are known, call THIS tool immediately — searching the catalog, get_guidancemetric, or polling Tasks never starts a build. A successful responsecount withover a new task_id is the only proof of submit; do not claim started/restartingpart untillayer then.(e.g. ThenZIPs) followand do_this_nextadds onlythem withas thata new task_id. When workflow_advisor returns next_tool=auto_build, call auto_build next. Canonical examplealignment —(TAL); 3existing TXalignments ZIPstay. territories,Needs workload-only,the 30-minuser's dwellchoices: build_mode={mode:build_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_countterritory_count, fixed_workload_target, scoped_split. For workload targets+ (e.g.target_workload 40-hourin territories)hours, use build_mode={mode:or fixed_workload_targetscoped_split), target_workload: 40}objective (territories only approximate the target). ALWAYS askworkload_bias for dwell/onsite time before calling — Auto Build always computes territory workload hours= (drive + dwell), even when balancingtime on+ adwell; metric or account count. Pass dwell_time only after+ theymetric_bias confirmfor 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,Revenue; askbiases whethersum to aggregate workload across a schedule period (pass visit_frequency_field) or ignore it (pass ignore_visit_frequency=true100). 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_userdwell_time (HITL-025 — not a server failure). build_mode may be omitted when elicitation can fill it. Workload is drive time plus dwell — not Revenuecolumn or any metric column.a Whenscalar 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 (Q5states) only. Confirm balance. dimensionEach (Q2)missing andchoice biasreturns (Q3)CLARIFICATION_REQUIRED with the user whenquestion unclearin —ask_user; 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 askdeclared whichvisit-frequency 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_idalso andneeds analysis_panel=singlevisit_frequency_field (or load_analysis_panel) so stats appear in the MC dock — not chat-only. Part scope defaultsignore_visit_frequency. topart_scope: bbox_intersect (ZIPs intersecting the account-pointdefault; bbox)parts —near geographicthe proximityaccounts, not state/attribute scope. When the usercan namesreach anational statescale) or region ('TX ZIPs only',explicit 'Texaswith only')part_filter, pass part_scope=explicit ande.g. part_filter={state_abbr: TX} immediately; do not default to. bbox_intersectWith (canmap_session_id pullthe tensopen ofmap thousandsis ofthe nationalinput; ZIPs)ts and do not query_parts first for an obvious state filter. Scope fieldsts_handle 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 qualitynot andneeded. returnsReturns a NATIONAL_PART_SCOPE warning rather than silently switching geography. Long partitions publish named 35–42% subphases (travel cache,task; powerthe solve,result bordercarries refinementtal_id, compactnessts_handle, 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: ingest_accounts done,shape part_layerfigures chosen(min_solidity, viewer connected (human-in-looppolsby_popper). Use direct_build for known assignments; account_build to group by attribute. Appends a TAL; does not replace existing alignments. Dissolved leaves report min_solidity beside mean_polsby_popper and min_polsby_popper. Gate shape from those figures rather than recomputing them from a download. Next: analyze with analysis_panel=single. Full atom: ezt://guidance/workflows/build-from-accounts. Scenarios: S003,reports AB-001..017,the MC-011.statistics.

 ⟨34 unchanged words⟩ ":null,"title":"Expected Revision"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"ignore_visit_frequency":{"anyOf":[{"type":"boolean ⟨216 unchanged words⟩ 

[Tier 1 — Routing]Sequences When:and drivedrives a listset 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. Whene.g. a visit-frequencytechnician columnfrom ishome onto the point layerdepot, then the wordday's routecalls, isand ambiguousback —home: confirmreturns the user wants a driving itinerary oforder, thoseroad stopsdistance, notdrive schedule_visitstime, before callingper-leg thistimings, tool.and Prerequisites:geometry afrom TomTom or Azure Maps, keyand ondraws the server; stopspath referencedwith bynumbered point_layerstops muston alreadythe beopen ingested,map or(map_session_id). passCreates inlineno lat/lon.territory TERRITORYand STOPS:changes afterno aassignment. TALroute_type 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 iduser's fromchoice: thecircuit last(returns buildto (leaf_territories[].territory_idstart), not a displaytour label.(ends startat isthe exactlyrequired oneend stop (home, depot), or open_tour (one point_idway). The territory filter belongs on stop_sets, never on start. ORDERED STOP SETS: stop_sets are visited in the order suppliedgiven and optimizationno NEVERstop 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,sets; 'as_given'order tois keepoptimize itor fixed.as_given; group_by_field splitsadds onepriority setbands. intoStops orderedare bandsinline oncoordinates aor columnpoint-layer valuereferences (e.g. route_priority: every 1 precedes every 2, optimized inside each bandsource.filter.territory_id). 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 NEWnew route_id ADDSadds a route (10 Houston routes coexist, each with its own legend row andsecond color).route; Reusingrecalculating an EXISTINGexisting route_id REPLACES that route inreplaces placeit, which is the waye.g. 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-mintedstop. iddwell_time is finestored for a one-off).analyze_routes. UseRoute delete_routedrive totime dropis a whole route; per-route workload facts come from analyze_routes,different nevermeasure from analyze. Pass dwell_time when you want route workload recomputable later; it is stored as provenance and never invented.territory QUOTA:workload. billableNo 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 isreturns all-or-nothing:ROUTING_NOT_CONFIGURED; past the cap it returns PROVIDER_QUOTA_EXCEEDED with limit, used,monthly remainingquota, and period_resets_at ratherPROVIDER_QUOTA_EXCEEDED. thanReturns 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.task.

 ⟨33 unchanged words⟩ "default":null,"title":"End"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"include_geometry":{"default":true,"title":"Include ⟨88 unchanged words⟩ 

[Tier 1 — BalancedGroups Pointthe Grouping]points Partitionof one ingested point layer directly into balanced point groups withclusters CCPDdirectly, withoutwith usingno ZIPs/countiesZIP or creatingpart alayer TAL.and Theno toolterritory addsalignment. Writes group_field (default group_id) toon every point and color-classifies that field incolors the linked Map Component. Thatlayer writeby replacesit, thereplacing layer'sany existingprior color classification (including a leftover color_classification ramp). Sizesize 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}stay). 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 theNeeds samebuild_mode sizing,(fixed_territory_count balance,or biasfixed_workload_target), visit-frequencyobjective, and dwell questions; workload means in-group drive time plus dwelldwell_time, never a metric column. Never invent dwell. build_mode supports fixed_territory_count and fixed_workload_targetas only.in SUBSET:auto_build; a named state or region on an already-ingested layer — Florida schools, TX accounts onlymissing —one usesreturns point_filterCLARIFICATION_REQUIRED onwith the firstquestion. call,point_filter (e.g. point_filter={STATE: FL}. Keys are point properties (one value or a list). Do not re-ingestclusters a filtered extract. Do not pass part_filter or part_scope (those belong to ZIP/part tools). Do notsubset clusterof the national layer.layer; Unmatchedunmatched points stay on the layer with group_field cleared and appear as an Ungrouped legend, class.ungrouped. TheMax 10,000-point cap000 appliespoints 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, depotsseed_point_layer, branch offices — pass seed_point_layer=<that layer>. It must be a SECOND ingestedsecond point layer, notsuch point_layer.as Eachtechnician seedhomes, anchors exactly ONEone group, soper seed (the seed count must matchmatches the group count (fixed_workload_target must derive that, sameelse countseed_count_mismatch) or the call fails INVALID_REQUEST with blocked_by=seed_count_mismatch.; seed_attraction (0-100, (default 70) controlsis the holdpull onof 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 inon 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 notgroup. produceReturns a TAL. Use auto_build for territories. Followtask; the returned task. The result lists groups (group_id,with point_count, workload_hours, point_ids). Full atom: ezt://guidance/workflows/cluster-points. Scenarios:and CP-001..005.point_ids.

 ⟨51 unchanged words⟩  Label Prefix","type":"string"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨119 unchanged words⟩ 

[TierUpdates 2durable —map Durablesettings Mapon Config]the When:Territory setSolution orand updaterefreshes the live map: project_name (themap durableheading), TSloaded_part_layers short([] namehides usedZIP/part asoutlines; thebuilds Mapnever Componentload headingthem), 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:zoom point_layer_classifications(default isview; the way to recolor/resize/reshape points on an openlive map — never export GeoJSON, compute breaksjumps client-sidethere), and repost apoint TS.symbology. Eachpoint_layer_classifications entryentries isare {point_layer, field, method: quantile|equal_interval|categorical|manual,quantile class_count| (2-12),equal_interval channel:| color|size|shape,categorical optional| colors/sizes/shapesmanual, optionalclass_count style:{color,size,opacity2-12,shape} for the layer base symbol}. Supported shapeschannel: circle|square|triangle|diamond|star|cross|house|pin|flag|hexagon|pentagon|shield|arrow_up|building (aliasescolor home→house,| marker/map_pin→pin,size hex→hexagon,| arrow/up→arrow_upshape, warehouse/depot→building,optional plus/x→cross).colors/sizes/shapes/style}; Thethe server computes breaks from the in-session points, writes point_layers[].<channel>_classification, pushes config_changed,breaks 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).layer; clear:true with point_layer and channelremoves dropsone. thatShapes channelinclude classificationcircle, 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 onesquare, entrytriangle, perdiamond, layerstar, tocross, givehouse, twopin, pointflag, layershexagon, distinctpentagon, colorsshield, orarrow_up, shapes.building. classification (without a point_layer) staysis a project-level map_config patchsetting andthat does NOT paint points; a point-layer-targeted classification is routed to symbology with anot warning.color PARTpoints. LAYERSInput: builds never load a part layer overlay; ZIP/county outlines appear only when named. loaded_part_layers=[ids] shows them, loaded_part_layers=[] hides them all (active_part_layer clears too), and the choice persists across later builds. request_part_selection loads the part_layer it selects on. 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-1map). 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.ts.

 ⟨69 unchanged words⟩ ":null,"title":"Expected Revision"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"loaded_part_layers":{"anyOf":[{"items":{" ⟨112 unchanged words⟩ 

[Tier 2 — Territory From Parts] When: create or updateCreates one leaf territory from committed part IDs (manual MC-005 build ora RL-011/012).list Prerequisites:of 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 toe.g. showa thecommitted newmap territoryselection)., Ifin result.map_refresh.notifieda isnew falsealignment or status isan rebind_required,existing callone get_map_visualization(job_id=<this job>tal_id). With no open MC, pass ts_handle frommap_session_id the prior result (never repost inline ts when a handle exists);live themap's newTerritory TALSolution is appended to that TSupdated and therepainted; resultotherwise returnsts_handle (a new ts_handle.ts_handle is returned). map_session_id wins when both are passed. Completed result includes created_territory.territory_id, leaf_territories, and selection_summary (requested/unique counts plus duplicate_part_ids) — territory_name is a display label only (e.g. T1 → territory_id like tal-t1-t1). Later realign into this territorylabel; MUSTthe useresult's created_territory.territory_id (preferred) oris the exactstable leafid displayfor namelater whenedits, unique;plus neverleaf_territories inventand shorthandselection_summary (T3 ≠ Territory 3duplicate_part_ids) — if unclear, ask which leaf from leaf_territories. DWELL: this tool. createsDwell ais NEWoptional TALhere and doesis not inherit dwell_timeinherited from aan priorearlier auto_build.auto_build; Dwelldwell_time is NOT required to create the territory (same as direct_build). Optional dwell_time={type:scalar,value,unit} stamps build_provenancerecorded for later Analyze.analyze. Without dwellit, Analyze still runs andanalyze reports every other statistic but OMITSexcept 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-bandand forreturns dwellworkload_omitted.ask_user. whenReturns 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.task.

 ⟨21 unchanged words⟩ ":null,"title":"Dwell Time"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨85 unchanged words⟩ 

[Tier 2 — Delete Route] Whendelete: dropremoves aone whole route from the map and the TSTerritory (e.g.Solution 'deleteand the Tuesday Aopen route'map, 'remove route houston-tue-a'). Prerequisites: map_session_id for an open MCin (preferred),one elsesynchronous ts_handle;call. plusNeeds route_id (or anthe route's exact unique route label). NOT for removing a single stop — for that, call calculate_route again with the SAME route_id and the remainingplus stops,map_session_id whichor replacests_handle. theA route inthat place.is Already-absentalready routesgone returnreturns ok with already_absent=true and no error.already_absent=true; Anan ambiguous label returns AMBIGUOUS_ROUTE with matching_route_ids — pass an explicit route_idmatching_route_ids. ratherA thansingle guessing.stop Synchronous:is noremoved task_id.by Verifyrecalculating the open map legend no longer lists thesame route.route_id Scenarios:with RT-010.calculate_route.

{"properties":{"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨31 unchanged words⟩ 

[Tier 1 — Delete TAL] When: wipeDeletes 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. 'removeTAL: the'the territory layer', 'wipe all'all territories',) 'removefrom the alignment', 'clear tal-tx-10t before rebuild'). Prerequisites:Territory map_session_idSolution forand anthe open MC (preferred)map, elsein ts_handle;one plussynchronous call. Needs tal_id (or anthe TAL's 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 /, noplus Realignmap_session_id progressor overlay.ts_handle. Points, part-layer overlays, and routes stay; active_tal_idthe becomesmap switches to a remaining TAL, __points__,alignment or __empty__. Already-absent returns okto withpoints already_absent=true.only. AmbiguousA labelTAL returnsthat AMBIGUOUS_TAL.is Next:already verifygone thereturns legendok droppedwith thealready_absent=true; alignment,an thenambiguous auto_buildlabel /returns account_buildAMBIGUOUS_TAL. /One direct_buildterritory whenis rebuilding.removed Scenarios:with HITL-057,delete_territory T-134.instead.

{"properties":{"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨31 unchanged words⟩ 

[Tier 1 — Delete Territory] When: deleteDeletes one leaf territory from an existing TAL (e.g. 'delete T1', 'remove territory West'). Prerequisites: ONE current TS reference —alignment; preferits map_session_idparts forbecome anunassigned. openNeeds MCtal_id, else ts_handle or ts; tal_id; territory_id (stablethe leaf id from created_territory.territory_id / leaf_territories preferred, or anits exact unique display name — do not invent shorthand like T3 for Territory 3; ask if unclear). Do NOT invent part_ids or call auto_build. This tool collects the leaf's part_ids and runs Realign remove_parts + remove_empty_territories (same engine as RL-013). To wipe an entire TAL / alignment before rebuild, call delete_tal instead — never N× this tool. When a rep leaves and the neighbors should takeTerritory overSolution thefrom territorymap_session_id, call territory_merge instead — this toolts_handle, leavesor thets. deletedA territory'sterritory partsthat unassigned.is Already-absentalready territoriesgone returnreturns ok with already_absent=true (no job). Next: follow the returned Tasks status operation until completed,and callno itstask; resultotherwise operationreturns once,a thentask verifyand the open map legend norepaints. longerRelated: liststerritory_merge thehands territorya ANDleaving therep's territory fill/outline is gone from the canvas (not just the legend) before claiming success. Geography-only delete does not requireto Analyze.its Scenarios:neighbors; feedbackdelete_tal delete-territory,removes RL-013a wrapper,whole T-087alignment last-leafin paintone clear.call.

 ⟨8 unchanged words⟩ ":null,"title":"Expected Revision"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨118 unchanged words⟩ 

[TierBuilds 1territories —from Knownknown Assignmentspart-to-territory Builder]assignments When:(a userZIP-to-territory hassheet explicitor part-to-territoryfile, assignmentsincluding (spreadsheet,a legacythree-level file,region/district/territory hierarchicalhierarchy via territory_path). assignments_handle mustand beadds athem serverto uploadthe handleTerritory (aup_...)Solution fromas request_assignment_uploada —new csv_text/csv_file/assignments,alignment or(TAL). aAssignments POSTcome ofinline theor CSVas filean toassignments_handle its(aup_...) key-lessfrom result.upload_url.request_assignment_upload. LegacySheets spreadsheetswith (Postal Code +plus Territory/Region/Division) are auto-mappedcolumns whenare staged.mapped Conflictingautomatically. duplicateDuplicate part_ids default tofollow duplicate_part_policy=keep_firstduplicate_part_policy (firstdefault winskeep_first). Prerequisites: part_layer chosen; viewer connected for MC-first; ts/ts_handleReturns optional.a Nottask; forthe accountresult pointcarries locations—usetal_id ingest_accounts.and Notts_handle forand balancedpaints partitioning—usethe auto_build.open Notmap. forLocation attributepoints grouping—useload account_build.with Next:ingest_accounts; verifybalanced TALpartitions income MCfrom (MC-011),auto_build; analyzegrouping +by load_analysis_panel.a Scenarios:column DB-001..005,is MC-011.account_build.

 ⟨43 unchanged words⟩ ":null,"title":"Expected Revision"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨127 unchanged words⟩ 

[Tier 1 — Router] Deterministic entry point for ambiguousMaps ora open-endedfree-text territory requests. When: the user's goal or build type is unclear and you want the correct workflow beforerequest acting.to Prerequisites:a noneworkflow. (staticRead-only keyword routing; no compute).compute. Returns an intent_category, the recommended tool order, the Tier 1main tool + Tier 2 alternatives(tier1_tool, required_inputs,null clarifying_questionswhen tothe askrequest whenis inputsambiguous) areand missingalternatives, a guidance_urirequired_inputs, (ezt://guidance/workflows/{name})clarifying_questions for the fullmissing atominputs, and `guidance` — the same EMEPworkflow atomguide inlinedinline as guidance {uri, title, excerpt, truncated}, so you do NOT need a second resources/read to get the workflow text. Use. itCovers tobuilding disambiguateterritories (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 bestcluster_points, orderseed_build) /, reachable-areaediting (a drive-time or drive-distance area around origins — service area, catchmentrealign, coveragesplit, isochronemerge, which routes to isochrone_buildrebalance) / periodic-scheduling (a recurring cadence — 'every 30 days', 'twice a month' — and which day each visit lands onanalyze, which routesgeocoding toand schedule_visitsingest, never auto_build or cluster_points) / push-to-designer (an EasyTerritory Designer rolodex project fromshowing a TS: export_geojson then POST FromTerritorySolution to createZIP or PUT .../Projects/{projectId}/... to update; territories,part pointslayer, and routes import; ezt_pat_; there is no MCP push tool), /drive-time pull-from-designerareas (a Designer rolodex project into the MCP: GET REST/Agent/Projects thenisochrone_build), GETrecurring .../Projects/{projectId}/TerritorySolutionvisit withschedules ezt_pat_(schedule_visits), then import_geojson geojson_gzip; thereand ismoving noa MCPTerritory pullSolution tool).to Scenarios:or AB-016,from ACB-003,EasyTerritory wrong-build-tool.Designer.

[Tier 1 — MC-First Gate] When: after get_map_visualization returns map_url andReports beforewhether anythe compute,person build,has analyze,the ormap selectionopen work(viewer_status.connected) withfor a human in the loop. Prerequisites: map_session_id from get_map_visualization. Next: ingest, configure_map, build, realignget_map_visualization, or analyze once viewer_status.connected. Surface-agnostic: the in-chatwaiting MCPup Appto shellwait_seconds connects(max the30 sames sessionper overcall; the same SSE channel, soresult thisreports gaterequested_wait_seconds worksand unchangedmax_wait_seconds). whetherWorks the human is lookingsame atfor the in-chat map orand the map_url tab. Do not skip it on anReturns AppsVIEWER_NOT_CONNECTED host.while wait_secondsthe blocksmap atis moststill 30closed; sthe persame call (largercan valuesbe arerepeated clamped;while the result reports requested_wait_seconds andperson max_wait_seconds).opens Onit. VIEWER_NOT_CONNECTEDBuild, callanalyze, againand withselection theresults samepaint map_session_idlive whileonce the user opens map_url. Scenarios:viewer MV-001,is I-1.connected.

{"properties":{"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"title":"Map Session Id", ⟨25 unchanged words⟩ 

[Knowledge Retrieval] TraverseTraverses the EMEP knowledge graph from a topic file (e.g. 'workflows/realign-by-selection.md') to find related guidance, up to `depth` hops. Returns  ⟨8 unchanged words⟩ 

[Knowledge Retrieval] ListLists 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.

[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 ⟨31 unchanged words⟩ 

[TierExports 2the —territory Projectsolution save]as Theone onlyGeoJSON Territoryfile Solutionto export.share, Materializearchive, theor workingopen GeoJSONin FeatureCollectionEasyTerritory (Designer: territory polygons with part_ids, point featurespoints, and route pathsroutes +with 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. Theeach resultcarrying carriesits geojson_artifactdisplayed {artifact_id,style. bytes}tal_ids, zip (default true = gzip download)point_layers, 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.route_layers Setnarrow include_points=falseit; orinclude_points include_routes=false/ toinclude_routes dropomit a family. Reopen with import_geojson, then get_map_visualization(ts_handle=...). Paint travels with the exportInput: every feature and point_layers[] / route_layers[] entry carries style {color, opacity, size, shapemap_session_id, weight} exactly as shownts_handle, so reopen and Designeror importa needcompleted nobuild restyling.job_id. AnReturns EasyTerritorya Designertask rolodexwhose projectresult is this download POSTedgeojson_artifact toplus Designera REST/Agent/Projects/FromTerritorySolutiondownload_url (new)GET orwith PUTthe toAPI .../Projects/{projectId}/FromTerritorySolutionkey; (update).gzip Territories,unless pointszip=false), and routes import.not Therean isinline nobody. MCPimport_geojson pushreopens toolthe (ezt://guidance/workflows/push-to-designer).file.

{"properties":{"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"include_points":{"default":true,"title":"Include ⟨98 unchanged words⟩ 

[Tier 1 — Delegation Extract]Extracts When:one seniorregional plannerbranch sendsof a regional subtreehierarchical toalignment a(by delegatebranch_rollup_territory_id foror boundedbranch_territory_path) editing.into Prerequisites:its masterown TSTerritory withSolution, hierarchicalso TAL;a branchdelegate rollupcan oredit pathjust identified.that Next:region. storeReturns branchthe extract +plus branch_metadata;branch_metadata, delegatewhich opensreintegrate_branch MCneeds onlater. extractexclude_locked only.(default Scenarios:true) DL-001,leaves DL-002.locked territories out.

 ⟨67 unchanged words⟩ ":null,"title":"Expected Revision"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨43 unchanged words⟩ 

[Tier 1 — Plain-language orchestrator]: Usetakes whenrequest (the exact granular tool is unclear or when a greedy/file-holding clientgoal) wantsand toruns completethe anmatching actionworkflow in one step. Prefer granular tools directly when you know thecall, step.optionally Passwith requestcsv_file (your goal) plusa optionalhost csv_filefile /parameter), accounts_handle /, assignments_handle /, map_session_id, /or ts_handle. For anAn uploaded CSV, pass csv_file as the ChatGPT/OpenAI file parameter; ezt parses/stagesis itparsed, server-sidestaged, and can run ingest_accounts with map_session_id so points appearingested ononto the open map. For fixed-workload builds, args.target_hourstarget_hours / args.workload_target areworkload_target normalizedmap to auto_build build_mode.mode=fixed_workload_target. Modern form-capable clientsa (protocolfixed-workload >=auto_build. 2026-07-28)Missing maybuild answerinputs missing(part part_layerlayer, tal_labelalignment name, sizing, dwellbalance, anddwell) optionalreturn balanceCLARIFICATION_REQUIRED in-bandwith (alignedthe withquestions. auto_build);The legacygranular hoststools keepdo CLARIFICATION_REQUIREDthe /same ask_usersteps (HITL-025).individually.

 ⟨46 unchanged words⟩ ":null,"title":"Csv File"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨43 unchanged words⟩ 

[Tier 1 —Geocodes Geocodea Only]list When:of geocodecustomer 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 geocodesto inlinecoordinates with accept_suboptimal_geocodes default true). Use this tool when the user must verify geocode qualitymatch first;confidence, setwithout accept_suboptimal_geocodes=trueloading tothem acceptas ZIP-centroid/suboptimala matches.point Addresslayer. columns:Accepts address/address_line1/street, city, state, and postal columns (common CRM headers auto-mapped). QUOTA: billable provider calls are capped per API key per calendarmapped). month.accept_suboptimal_geocodes=true Cacheaccepts hitsZIP-centroid costmatches. nothingCached andaddresses are never counted, so never set use_cache=false orfree; force_regeocode=truebillable tolookups workcount aroundagainst a cap — that turns free hits intomonthly paidper-key calls.quota, Pastand thepast capit the toolresult returnsis PROVIDER_QUOTA_EXCEEDED carryingwith limit, used, remaining, and period_resets_at; an operator must raiseperiod_resets_at. theReturns capgeocoded_rows, so report those numbers instead of retrying or splitting the batch. Next:which passingest_accounts result.geocoded_rowscan toload. ingest_accounts or exportalso pointgeocodes layer.on Scenarios:its GC-001..006.own.

 ⟨25 unchanged words⟩ "Force Regeocode","type":"boolean"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨51 unchanged words⟩ 

[Tier 1 — Startup Guide + Handle]Returns CALLthe THISEZT FIRST.MCP Read-only.operating Whenguide: session start, afterthe blocked_by=guidance_required,cross-tool orworkflow whenorder theand shared rules are unclear. Returns result.text (the short cross-tool briefresult.text, same text as server instructions), result.guidance_handle (the rotating code every territory/map toolserver requiresinstructions), result.server_version (this, server'sand productresult.seat version;for the same string as serverInfo.version), andcaller's result.seatkey (plan standard|trial, key_expires_at, and quota_remaining for geocode/route/isochrone — tell a trial user when the trial or an allowance isgeocoding, closerouting, toand runningisochrone outrequests). Per-tool rules are on that tool's description. WorkflowRead-only. essaysUseful areat inlinedthe asstart guidanceof ona discover_intent,session workflow_advisor,or andfor blocked_by.a Exempt:host get_guidance,that submit_feedback,does discover_intent,not workflow_advisor,show ep_*server tools.instructions.

[Tier 2 — MC Selection Poll] When: readReturns the latest committed MC session selection — especially whenmost Monicarecent startedcommitted selection from the legend finger icon and then tells the agent what toon doan withopen 'mymap selection'session (no prior request_part_selection in this turnmap_session_id). Prerequisites: map_session_id of the open MC. Returns part_layer +, part_ids, (+and 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}]selection derivedcame from every returnedrequest_part_selection. part_idCovers usingselections 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).person Ifstarted unclear,from askthe whichmap leaf.legend. Dorealign nottakes resendthese thepart_ids TSas ormoves requestwith a new selection. Scenarios: MC-004 variants, user-initiatedleaf select.territory_id.

{"properties":{"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"title":"Map Session Id", ⟨8 unchanged words⟩ 

[Tier 1 —Opens MC-Firstthe Entry]interactive FIRSTterritory stepmap of(Map non-headlessComponent) territoryand workreturns (invariantmap_url I-1).and When:map_session_id. openOpens a blank map for planning, or open/reuseshows the user's Maplatest Componentstate forof an existing Territory Solution (TSe.g. yesterday's work) from ts, ts_handle, or a completed job.job_id. PassIdempotent new_project=trueper touser_id: replacea thesecond livecall workspacereturns withthe ansame emptymap. project;new_project=true omittedreplaces empty+viewthe reusesopen theworkspace existingwith project.an Optionalempty project. 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):selection. Apps-capable hosts render thisthe map in chat from (ui://easyterritory/map-viewer (_meta.ui.resourceUri); every other client — including Cursor —clients opensopen map_url in a browser tab. map_url is always returned. Do not open a second surfacebrowser. orLater callmap thistools tooltake againmap_session_id. toensure_map_viewer 'fix'reports awhen map.the Scenarios:person MC-000,has MC-001,the MV-001,map S004.open.

 ⟨20 unchanged words⟩ ":null,"title":"Expiry Seconds"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"interaction_flags":{"anyOf":[{"additionalProperties":true, ⟨85 unchanged words⟩ 

[Tier 2 — Selection Poll] When: poll or retrieve committed part IDs afterReturns request_part_selectionthe ORstate afterof Monicaa startsmap selection from the MC legend finger icon. Prerequisites:task (selection_task_id from request_part_selection, or from map session state (active_selection_task_id onin ezt://map-sessions/{id}/state). Poll loop: while status=awaiting_user_selection, sleep recommended_poll_delay_ms (fallbackstatus poll_interval_msawaiting_user_selection, min 250ms) and poll again until status=committedcommitted, expired, or cancelled. Response includes do_this_nextcancelled, and poll_loop while awaiting. If the user alreadyonce committed and says 'add mythe selectionselected topart_ids …',(with callassigned onceand forunassigned thepart_ids committedwhen taska (orTAL useis get_map_selectionactive) and. proceedWhile —awaiting, dothe notresponse startcarries arecommended_poll_delay_ms. newCommitted selection.part_ids Next:feed realign, create_territory_from_parts, or analyze scoped to selection.part_ids. Scenarios: AN-007, RL-008.analyze.

{"properties":{"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"selection_task_id":{"title":"Selection Task Id", ⟨8 unchanged words⟩ 

[Tier 2 — Project reopen] ImportOpens a GeoJSON FeatureCollection (standardplain points, or ana export_geojsonterritory artifact,file includingthis gzip/zip).server Returnsproduced, ts_handleplain +or summarygzip/zip) —as passa ts_handleTerritory toSolution get_map_visualizationand /returns analyzets_handle /and export_geojsona next;summary. doInput: notgeojson repost(object), thegeojson_text, GeoJSONor body.geojson_gzip Arbitrary(base64). territoryTerritory polygons WITHOUTwithout part_ids are rejectedreturn (TERRITORY_POLYGONS_WITHOUT_PART_IDS) unless you explicitly pass part_layer plus overlay_policy="centroid_within" tooverlay_policy=centroid_within assignassigns parts whose centroids fall inside each polygon.by Optional:centroid. point_layer (name fornames imported points), tal_label. Supply geojson (object), geojson_text (JSON or sniffed gzip/zip), orpoints; geojson_gziptal_label (base64names gzip/zip).the Analignment. EasyTerritory Designer rolodex project arrives here too: GET Designer REST/Agent/Projectsprojects (list) then GET .../Projects/REST/Agent/Projects/{projectId}/TerritorySolution with the user's ezt_pat_ Bearer, and pass the (gzipped) fileimport as geojson_gzip. There is no MCP pull tool (ezt://guidance/workflows/pull-from-designer).

 ⟨31 unchanged words⟩ ":null,"title":"Geojson Text"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"overlay_policy":{"anyOf":[{"type":"string ⟨44 unchanged words⟩ 

[Tier 1 —Account Dataingest: Intake]loads When:account load/addor account/locationlocation rows or(CRM accountrecords, a CSV, a spreadsheet) as point data intoon a TSnamed point layer. ALWAYSlayer beforeof account-derivedthe buildsTerritory (auto_buildSolution, account_build). Prerequisites: MC-first + viewer connected whento humanadd verifiesthem points;to ts/ts_handlethe optional.map, Geocodesgeocoding rows lacking valid coordinates (accept_suboptimal_geocodesthat defaultslack truecoordinates. forRows bulkcome address-onlyinline CSVs(rows). Recognized addressor columns:as address/address_line1/street,accounts_handle city,from staterequest_account_upload, postal columns,which plushandles commonlarge CRMfiles; headersa (e.g.client Addressfile 1:path Streetis 1).not Coordinatereadable passthroughby acceptsthe case-insensitiveserver. GISCoordinate headers latitude/lat/LATlatitude/lat and longitude/lon/lng/long/LON (no rename required);longitude/lon/lng pass explicit latitude_field/longitude_field forthrough; other headers (e.g. Addressnames 1:need Latitude).latitude_field/longitude_field, Ifand unused numeric lat/lon-likecoordinate-like columns exist and ingest would otherwise bulk-geocode, the job fails fast withreturn 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(needs_coordinate_fields) geocode_query_countinstead onof a file that had coord-like columns, call tasks/cancel or tasks_cancel and fixbulk headers/fields.geocode. id_field must beis a UNIQUE businessunique 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, …synthesized 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,; andduplicates visit-frequencyreturn columns.needs_unique_row_id. PassOnly confirmeddeclared businesscolumns metricsare askept: 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 idworkload_fields, coordinatesdwell_time_field, labelvisit_frequency_field, 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 andsearch_fields; 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 insteaduse 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. WITHOUTan map_session_idundeclared thecolumn pointsreturns landUNDECLARED_FIELD. inReturns 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 calltask; the indicated result operation once and inspect the terminal one-liner field, viewer_outcome,reports 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=truemap_refresh, 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 COMPOSE: linked ingest is non-destructive for prior part-layer overlays — previously configured loaded_part_layers remain on the session with the new points. Verify both the point layer AND any expected part overlays are still present before claiming compose success; points-only adoption does not mean those overlays disappeared. GEOCODE QUOTA: billable provider calls are capped per API key per calendar month; cached addresses and coordinate passthrough are free and never counted. When the cap runs out mid-file the ingest is NOT refused — rows covered by the remaining budget are geocoded and ingested, and the rest arrive in failed_rows with reason_code=PROVIDER_QUOTA_EXCEEDED plus a resultgeocode quota block naming limit, used, remaining, unserved_row_count, and period_resets_at. Report that instead of re-running the ingest; the blocked rows need a raised cap, not a retry. Next: configure_map if needed, then choose the build tool. Full atom: ezt://guidance/workflows/geocode-and-ingest. Scenarios: IA-001..005, GC-002, GC-003, S003.shortfall.

 ⟨76 unchanged words⟩ ":null,"title":"Grouping Fields"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"id_field":{"default":"row_id","title": ⟨182 unchanged words⟩ 

[Tier 1 — Isochrone Build] When: drawDraws the area reachable by DRIVINGdriving 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 notadds balanceeach workload.area Prerequisites:as a TomTom or Azure Maps key on the server (no key → ISOCHRONE_NOT_CONFIGURED, no degraded mode — neverterritory substitutein a straight-line radius); and, for point-layer origins, ingested points plus ts_handle or map_session_id.drive-time Inlinealignment. origins need no TS. No part layer is involved. 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.reference. bands are: [{time_budget_seconds} |or {distance_budget_meters}], one budgetunit per band, and every band in a call must use the SAME unit (mixing returns MIXED_BUDGET_TYPES otherwise).; Oneone band →gives one leaf per origin; several bands → a rolluparea per origin with one leaf per band. Cost is origins x bands provider calls, capped by TOO_MANY_ORIGINS (default 25) /several TOO_MANY_BANDSgive (defaultnested 5).areas. QUOTALimits: those billable calls also draw on a per-API-key monthly cap. The whole fan-out is claimed before any call goes25 outorigins, so a build that does not fit returns PROVIDER_QUOTA_EXCEEDED with5 limitbands, used,6 remaininghours, and period_resets_at having spent nothing. An operator must raise the cap; report those numbers instead of retrying with fewer bands.500 LIMITS:km; travel_mode is 'car' or 'truck' ONLY — neither provider offers a walkingcar or cycling reachable range, unlike calculate_route. time_budget_seconds <= 21600, distance_budget_meters <= 500000 (BUDGET_OUT_OF_RANGE).truck; 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: eachsupported. territoryAreas ISare the provider's exact polygon — no part layer, no part_ids. Bands nest and nearby origins'provider polygons overlap, and the map paints them overlapping (tightest onmay top).overlap; analyze counts an accountaccounts in EVERYevery area that contains it (a 20-minute band includes its 10-minute accounts) and reports the accounts overlapping areas share. realign / territory_split / territory_mergecontaining /them. territory_rebalancerealign/split/merge/rebalance return ISOCHRONE_TAL_NOT_EDITABLE: re-run isochrone_build to change an area; delete_territory / delete_tal still remove one.ISOCHRONE_TAL_NOT_EDITABLE. A band budget is NOTnot territory workload and NOT route drive time — never report '20-minute band' as 20 minutes of workload or feedroute ittime. toNo auto_build.provider Async:key returns task_id — follow _meta.next_action (sleep_and_poll → consume_result) and sleepISOCHRONE_NOT_CONFIGURED; the authoritative sleep_ms, never estimated_remaining_ms.full Partialcall providercount failureis stillchecked buildsagainst the TAL and reports failed_requests[]. Then: analyze(tal_ids=[<tal_id>], map_session_id, analysis_panel='single') for per-area accountsmonthly andquota metricsfirst (needs an ingested point layerPROVIDER_QUOTA_EXCEEDED). Pass map_session_id here to paint the areas on an open map. Full atom: ezt://guidance/workflows/isochrone-territories.Returns Scenarios:a IS-001..IS-006.task.

 ⟨31 unchanged words⟩ ":null,"title":"Depart At"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨81 unchanged words⟩ 

[Tier 2 — Analysis Panel Display]Shows When:a showcompleted Analyzeanalyze JSONresult in the MCopen bottommap's analysis dock (single or comparisoncompare) after a completed analyze that omitted analysis_panel. Prefer. analyze(analysis_panel=single,Needs map_session_id=...)map_session_id soand the dock fills without this second call. Prerequisites: map_session_id; a full Analyze result — passanalyze task_id/job_id ofor the completedfull analyze job, or analyses=[<full Analyze result>]. The result must include(with tal_analyses and ts_identity (territory_metric_grids when metrics exist). Ats_identity; thina {tal_analyses}partial object isreturns INVALID_REQUEST, not an empty dock.). presentation_mode is single|compare|executive|diagnostic — territory_metric_grid is default_presentation.view inside the Analyze: payloadsingle, not a presentation_mode. Does not mutate TS. Re-run analyze after anycompare, TALexecutive, or point change (I-2).diagnostic. dismiss=true hides the whole dock, header bar included, and keeps the statsstatistics on the session. analysis_panel.dismissedChanges isnothing thenin true.the ATerritory laterSolution. analyze with analysis_panel=single shows the dock again. Omit analyses on a dismiss call. Dual surface:fills 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.

 ⟨20 unchanged words⟩ ":"Dismiss","type":"boolean"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"job_id":{"anyOf":[{"type":"string ⟨68 unchanged words⟩ 

[Tier 2 — Part Metadata]Returns When:attributes enrich(no orgeometry) filterfor parts before build, or inspect attributesof withouta geometry.part Prerequisites:layer part_layerlisted fromat ezt://part-layers. PassTakes exactly one of filter (e.g. {state_abbr: TX}) or part_ids; neither or both isreturns INVALID_REQUEST. To check that a part layer exists, read ezt://part-layers instead of probingPaged with an empty query. Next: direct_build, configure_map, or agent-side join before build. Scenarios: DS-002. Returns part_id and attributes only; no geometry.page_token.

 ⟨9 unchanged words⟩ "default":null,"title":"Filter"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"max_results":{"default":100,"title":"Max ⟨40 unchanged words⟩ 

[Tier 1 —Moves Realign]ZIPs When:or moveother parts between leaf territories within ONE TAL. Prerequisites: existing TAL plus ONE current TS(typed reference:ids map_session_idor (preferredones forselected anon openthe MCmap), ts_handle,from orone ts;territory expected_revisioninto isanother optionalwithin optimisticone concurrencyalignment (STALE_TS_REVISION → reload and retrytal_id). For: a committed ad-hoc map selection, call get_map_selection(map_session_id), thenZIP passmove. moves=[{part_id, to_territory_id}] for each returned, selection.part_idsor plusrealign_operation tal_idwith andpart_ids. theThe sameTerritory map_session_id.Solution Docomes notfrom repostmap_session_id (the full TS and do not startopen anothermap), selection.ts_handle, to_territory_idor mustts; beexpected_revision aadds leafoptimistic territory_idconcurrency (prefer created_territory.territory_id /STALE_TS_REVISION leaf_territorieswhen /the legendmap catalogchanged). Ato_territory_id display-nameis aliasa isleaf acceptedterritory_id onlyor asthat anleaf's exact, unique match to the leaf's actual namedisplay (e.g.name; 'Territoryan 3'unknown or 'T1' when that is the name) — do NOTambiguous inventvalue shorthandreturns expansionsUNKNOWN_TERRITORY_ID (T3or ≠AMBIGUOUS_TERRITORY Territorywith 3;available_leaf_territories. noA T→Territorycommitted mapping).map Itselection is NOT tal_id. On UNKNOWN_TERRITORY_ID / AMBIGUOUS_TERRITORY read error.details.available_leaf_territories andwith stopget_map_selection; guessing;request_part_selection iflets the spoken destination isperson stillpick unclear,parts askon the user which leaf (id or exact name). Visual moves with a destinationmap. knownremove_empty_territories indrops advance:leaves request_part_selectionleft with purpose=realign. Structuralno rebalance:parts. territory_split/merge/rebalance.Returns Next:a verifytask; the liveopen map refresh. Runrepaints. analyze + load_analysis_panelrefreshes onlystatistics when the TSmap 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,account EV-001.points.

 ⟨8 unchanged words⟩ ":null,"title":"Expected Revision"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨160 unchanged words⟩ 

[Tier 1Merges —an Delegationedited Reintegrate]branch When:(proposal mergeTerritory anSolution approvedfrom proposalextract_tal_branch) TSback into the master. Prerequisites:Needs branch_metadata, expected_master_revision;and proposalexpected_master_revision; TSreturns atSTALE_TS_REVISION currentwhen lineage.the STALE_TS_REVISIONmaster ifchanged mastersince moved—requestthe freshextract, extract.in Sequentialwhich mergescase only.a Next:fresh refreshextract masteris Analysisneeded. panelMerges (I-2).apply Scenarios:one DL-003,at DL-004,a DL-006.time.

 ⟨25 unchanged words⟩  Master Revision","type":"integer"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"map_session_id":{"anyOf":[{"type":"string ⟨65 unchanged words⟩ 

[Tier 2 — Data Intake helper] When: you have account/location rows or anStages 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 callfor ingest_accounts(accounts_handle=...). If the file includes metric, workload, visit-frequency, or dwell-time fields, stage the fileand herereturns firstupload_handle, inspect returned csv_headers / row keys, confirm role candidates, then pass metric_fields/workload_fields/visit_frequency_field/dwell_time_field to ingest_accounts. Continue only after ingest_accounts has loaded the points. WAYS TO STAGE (all return an upload_handle): (A) CSV on disk +and asuggested_ingest shellargs with network (Cursor, Claudea Code,geocode_plan. Codex,Four CLIways agents)in: call with no rows to get result.upload_url, then run result.curl_example — POST the rawCSV file with Content-Type: text/csv. Noto APIthe key:returned upload_url is(no theAPI credentialkey; (expires in 15 min; each POST appends to the same handle).minutes; Fastestfastest for large files; do not re-type rows into csv_text or rows chunks. (Bfiles) MCP, csv_file: pass the uploaded CSV as (a ChatGPT/OpenAIhost file parameter when available. (C) MCP, csv_text: pass csv_text=<raw CSV string> (whole file in oneraw callCSV, up to 16 MB) when you have no shell or no network. Preserve multiline, newlines — do NOT JSON-encode with PowerShell ConvertTo-Json (that corrupts rows into a single linepreserved). Use Python json.dumps, or MCP csv_file instead. (D) MCP rows: call with rows=<chunk>; appendchunks moreappended with upload_handle=<prior handle>.upload_handle. A local path in csv_file fails (UNREADABLE_FILE_REFERENCE); use (A). Every result carries a fresh upload_url for itsreturns handle;UNREADABLE_FILE_REFERENCE; an expired URL returns UPLOAD_TOKEN_EXPIRED —and calla againcall with upload_handle forissues a new one. 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.The Handlehandle is single-use (claimed by the ingest jobingest_accounts) and expires (defaultafter 1h).1 Scenarios:hour IA-001..005,by S003.default.

 ⟨23 unchanged words⟩ ":null,"title":"Csv Text"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"rows":{"anyOf":[{"items":{" ⟨38 unchanged words⟩ 

[Tier 2 — Direct Build intake] When: you haveStages part-to-territory assignment rows or(e.g. a legacyZIP-to-territory spreadsheet (e.g. Zip2Terr.csv with Postal Code +plus Territory/Region/Division) that you cannot inline in direct_build. Stage rows here, then callfor direct_build(assignments_handle=<upload_handle>). WAYS TO STAGE (all return upload_handle): (A)and CSVreturns onupload_handle. diskSame +four aways shellin withas networkrequest_account_upload: call with no rows to get result.upload_url, then run result.curl_example — POST the raw file with Content-Type: text/csv. No API key:to upload_url is the credential (expires in 15 min;no eachAPI POSTkey; appends).15 (Bminutes) MCP, csv_file: pass the uploaded CSV as a ChatGPT/OpenAI file parameter. (C) MCP, csv_text: pass csv_text=<raw multiline CSV> — preserve newlines; do NOT JSON-encode with PowerShell ConvertTo-Json (corrupts rows).newlines (Dpreserved) MCP assignments: pass assignments=<chunk, ofor rowassignment objects>;chunks appendappended with upload_handle. An expiredLegacy upload_urlcolumns returnsmap UPLOAD_TOKEN_EXPIREDto —part_id calland againterritory_path withautomatically. upload_handle.A Legacyfile columnsof (Postallocations Code,rather Territory,than Region,assignments Division)is auto-mapredirected to part_id + territory_path. Then: direct_build(assignments_handle=<handle>, part_layer=..., tal_label=...,request_account_upload. map_session_id=...).The Handlehandle is single-use and expires (defaultafter 1h).1 hour by default.

 ⟨38 unchanged words⟩ ":null,"title":"Csv Text"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"ttl_seconds":{"anyOf":[{"type":"integer ⟨22 unchanged words⟩ 

[TierLets 2the —person Humanadjust Spatialboundaries Input]by When:picking Monicaparts selects(e.g. partsZIPs) 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 askputs the human to type committed/done/go. User-initiated path: Monica mayopen alsomap startinto select mode from the MC legend finger icon on a part-layerpart_layer, rowfor (nopurpose priorrealign, request_part_selection).a Whennew theterritory, useror refersa toplain 'mylist. selection'Returns /selection_task_id; 'theget_part_selection partsreports Istatus selected'(awaiting_user_selection, read the open map session's latestthen committed selection via, get_map_selection(map_session_id)expired, or get_part_selectioncancelled) usingand active_selection_task_idthe fromcommitted ezt://map-sessions/{id}/statepart_ids, —and doits notresponse askcarries themrecommended_poll_delay_ms. toThe selectcommit again.happens Next:on realign,the create_territory_from_partsmap, or analyze with selection.part_ids.not Dualin surface:chat. indestination_territory_id anand Apps-capablerealign_operation hostpre-set thea humanrealign. selectsWorks on the in-chat map (ui://easyterritory/map-viewer); otherwise they select inand the map_url tab. The commitA pollselection loopthe aboveperson isstarted identicalfrom onthe bothmap surfaces.legend Scenarios:is S001,read MC-004..006,with RL-006..013.get_map_selection.

 ⟨32 unchanged words⟩ ":null,"title":"Expiry Seconds"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"new_territory":{"anyOf":[{"additionalProperties":true, ⟨81 unchanged words⟩ 

[Tier 1 — PeriodicSchedules Scheduling]recurring Whenvisits: accounts carryexpands aeach recurringaccount's cadence (e.g. every 7 days, twice a month) and the user asks which day each visit happens. Expands demand across a repeating horizon and packs itthe visits into daily work clusters (buckets) under onea technician-day workload cap. ThisDecides toolwhich decidesday theeach day.visit Neighbors:happens (auto_build, cluster_points, calculate_route. When the user said route and a visit-frequency column exists, confirm they want a schedule,cluster_points notdivide calculate_route,accounts beforeamong calling.people Itinstead); creates no TALalignment and assigns no technician. Prerequisite: ingest_accounts completed forNeeds point_layer (ingested, 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.declared, Required:else point_layerUNDECLARED_FIELD), visit_frequency_field, dwell_time, daily_capacity. Askand thedaily_capacity user(e.g. for{mode: dwellnot_to_exceed, andhours: the8}); dailymissing cap;dwell neveror inventcapacity them.returns frequency_unit=interval_daysCLARIFICATION_REQUIRED meanswith the valuequestion. isfrequency_unit: theinterval_days maximum(max 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. Valuesor invisits_per_horizon. never_visit_values (default 0, null, empty) are excluded and reportedlisted 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.excluded_accounts. bucket_workload_hours is in-bucket drive plus dwell with NO visit-frequency, multiplier:a itdifferent ismeasure neitherfrom territory workload nor route_workload_hours — never sum or compare them. Re-runningand withroute_workload_hours. theThe same visit_layer_name replaces that schedule ina place;schedule; a differentnew 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 stopone. onReturns stop_error.a Next:task. calculate_route over the visits layer filtered to one bucket_id to drivedrives that day. Full atom: ezt://guidance/workflows/periodic-visit-schedule. Scenarios: PS-001..PS-008.

 ⟨63 unchanged words⟩ "Frequency Unit","type":"string"},"guidance_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Guidance Handle"},"horizon":{"anyOf":[{"additionalProperties":true, ⟨124 unchanged words⟩ 

[Tier 1 — Seed Build] When: growGrows ONEone 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 coordinatesover firsta withpart thelayer addressuntil geocodingit tool;holds a map click already gives coordinates. TARGETtarget: target={type: 'location_count'location_count, value: N} or {type: 'metric_sum'metric_sum, field: <column declared in metric_fields at<declared ingest>metric>, value: X}. An undeclared field returns UNDECLARED_FIELD — re-ingest, withcounted metric_fields.from Fitan isingested CLOSEST:point growthlayer. addsAdds the nearestterritory adjacentas parta thatleaf stillof fitstal_id, then takes the smallest remaining neighbour only when overshootingor landsas nearera thenew targetalignment. thanFit stoppingis short.closest: target_status reportsis reached |, closest_under |, closest_over |, frontier_exhausted | max_parts_reached; a closest fit that misses the target also warns SEED_TARGET_UNDERSHOT, /or SEED_TARGET_OVERSHOTmax_parts_reached, with the signed differenceSEED_TARGET_UNDERSHOT/OVERSHOT —warnings telland the user, parts are indivisible. NO OVERLAP, EVER: with tal_id,difference. partsParts already in any territory of that layeralignment are never taken —taken; the new territory drifts awaygrows fromaround them instead (blocked_part_count, seed_offset_km)., Aand a seed inside an existing territory fails SEED_PART_ASSIGNED; pick anotherassigned seedpart orreturns reassignSEED_PART_ASSIGNED. partspart_scope=explicit with realign. There is no allow_overlap flag.part_filter SCOPE:confines 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 oncearea. perOne seed with the same tal_id; earlier territories becomeper blockedcall. forAn laterundeclared seeds.metric Async:field 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,UNDECLARED_FIELD. noReturns inlinea ts)task 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 onts_handle; the open map. Full atom:map ezt://guidance/workflows/seed-grown-territory.repaints Scenarios:with SB-001..SB-004.map_session_id.