Territory building is the core workflow of the EasyTerritory MCP Server. You describe what you need in natural language, and the AI agent translates your request into the right combination of build tools. This guide covers the four build approaches, the five build questions that shape every result, and worked examples you can try immediately.
Build Approaches
The server offers four build tools. Your agent will choose the right one based on your request, but understanding the differences helps you get exactly what you want.
| Tool | Best For | How It Works |
|---|---|---|
auto_build | Most situations — balanced territories from scratch | Groups nearby accounts into compact territories that meet your balance target. The recommended starting point. |
account_build | Grouping accounts by an existing CRM field (e.g., rep name, region) | Builds territories that mirror an attribute already on your accounts — no optimization, just geometry. |
direct_build | Importing an existing territory assignment file | Loads a pre-made assignment (CSV or JSON) directly onto the map. Use when you already have boundaries and just need to visualize or analyze them. |
cluster_points | Balanced groups on the point layer — no territory polygons | Adds a balanced group-id column to accounts using the same sizing, objective, dwell, and visit-frequency controls as auto_build. Colors the groups on the map but does not create a TAL or dissolve geography. |
In most cases, auto_build is the right choice — it creates geographic territories that optimize compactness and balance together. Use cluster_points when you want the same balance engine but only a grouping column on points (no ZIP dissolve). Use account_build or direct_build when the assignment already exists.
The Five Build Questions
Every auto_build and cluster_points call is shaped by five parameters. Your agent should confirm them before building. Do not invent dwell time — if there is no dwell column, give an average onsite time.
1. Sizing: Count or Workload Target?
Do you want a fixed number of territories (e.g., “build 5 territories”) or a target workload per territory (e.g., “build territories with roughly 200 accounts each”)? The former gives you control over the count; the latter lets the server decide how many territories are needed.
2. Balance Dimension
What metric should the server balance across territories? Options include account count, total revenue, total workload (visits × duration), or a custom numeric field on your accounts. The default is account count, which works well for most teams.
3. Bias
Bias controls the trade-off between compactness and balance. A compactness bias produces tighter, more contiguous territories. A balance bias produces more even workloads at the cost of stranger shapes. The default is balanced.
4. Visit Frequency
If your accounts have different visit cadences (e.g., key accounts visited weekly, others monthly), you can specify a visit frequency field. The server factors this into the workload calculation so that high-frequency accounts contribute more to the balance target.
5. Dwell Time
Dwell time is the average time spent at each account per visit (in minutes). Combined with visit frequency and drive time between stops, this gives the server a realistic workload estimate. There is no silent default — the agent should ask if your data has no dwell column.
Scoping to a State or Region
Most builds are scoped to a specific geography. The server uses two parameters to filter the parts (ZIP codes, counties, or other geographic units) included in the build:
part_scope: "explicit"
part_filter: { "state_abbr": "TX" }
This restricts the build to ZIP codes in Texas. You can also filter by region, custom territories, or any geographic attribute the server recognizes. If you omit scoping, the server builds from all loaded accounts, which is usually not what you want for a national dataset.
Example: Balanced Territories in Texas
Say this to your agent:
“Build 5 balanced territories from my accounts in Texas, workload-only, 30-minute dwell time.”
The agent will:
- Filter accounts to Texas (part_scope=explicit, part_filter with state_abbr=TX)
- Call
auto_buildwith 5 territories, balance dimension = workload, dwell = 30 minutes - Plot the resulting territories on the map, color-coded by territory
- Report the balance metrics so you can see how even the workloads are
If the balance is off, you can ask the agent to rebuild with a different bias or adjust the territory count. Iteration is fast — each rebuild takes seconds.
Example: Mirror Existing Rep Assignments
If your accounts already have a rep assignment field (e.g., assigned_rep in your CRM), you can build territories that match:
“Build territories that mirror my rep assignments. Group accounts by the assigned_rep field.”
The agent will call account_build with the assigned_rep field as the grouping key. Each rep becomes a territory. This is useful when you want to visualize existing assignments and analyze their balance without changing them.
After Building: Analyze and Load Results
Building territories is only the first half of the workflow. Once territories exist on the map, ask the agent to analyze them:
“Analyze the current territory assignment and load the results panel.”
The agent calls analyze to compute balance metrics, drive-time statistics, and compactness scores, then load_analysis_panel to display them in an interactive panel on the map. You can compare territories side by side and identify outliers that need adjustment.
Next Steps
- Territory Management & Realignment — Split, merge, rebalance, and fine-tune existing territories.
- Getting Started with EasyTerritory MCP — High-level overview of the full workflow.
- MCP Server Tools Reference — Full list of all 46 tools.
