EasyTerritory MCP

Ingest Accounts

ingest_accounts

Account ingest: loads account rows (CRM records, a CSV, a spreadsheet) as point data on a named point layer of the Territory Solution, to add them to the map, geocoding rows without coordinates. Rows come only as accounts_handle from request_account_upload (the user's file, csv_text, or rows; 100,000-row cap); its suggested_ingest carries these args. latitude/lat and longitude/lon/lng pass through; other names need latitude_field/longitude_field, and unused coordinate-like columns return CLARIFICATION_REQUIRED (needs_coordinate_fields). id_field is a unique key (default row_id); duplicates return needs_unique_row_id. Only declared columns are kept: metric_fields, workload_fields, dwell_time_field, visit_frequency_field, grouping_fields, display_fields, search_fields; to load a contractor list, layer_role=contractors adds trade_field, tier_field, capacity_field, service_zip_field (analyze_network_coverage). Later use of an undeclared column returns UNDECLARED_FIELD. Over geocode quota fails it whole. Returns a task with failed_rows and map_refresh.

Input Schema

Name	Required	Description	Default
`label`	No	Legend name for the point layer. Omitted: the point_layer id in title case (accounts is 'Accounts', schools_conus is 'Schools Conus').
`id_field`	No	Unique business key column. Duplicated label/name columns fail with blocked_by=needs_unique_row_id. With the default row_id and no unique column, the server synthesizes row-1, row-2, … when that column is absent.	row_id
`ts_handle`	No	Territory Solution reference (tsh_...) from a build, ingest_accounts, import_geojson, import_designer_project, or get_map_visualization; Territory Solutions are not accepted inline.
`use_cache`	No
`layer_role`	No	contractors marks the supply side of a service network (contractor, vendor, service provider) for analyze_network_coverage.
`tier_field`	No	Contractor column holding the network tier (e.g. Preferred). Retained like a declared column.
`label_field`	No		label
`point_layer`	No		accounts
`region_hint`	No
`trade_field`	No	Contractor column naming the trade(s) served (e.g. HVAC; comma-separated for several). Retained like a declared column.
`country_hint`	No
`metric_fields`	No	Agent-confirmed business metric columns (for example revenue, sales, units) to persist on point-layer metadata for downstream build/analyze tools.
`search_fields`	No	Declared columns searchable in the Map Component. Undeclared columns are discarded at ingest and later operations on them fail with UNDECLARED_FIELD.
`capacity_field`	No	Numeric contractor column holding capacity (e.g. jobs per month). Retained like a declared column.
`display_fields`	No	Declared columns shown in Map Component point callouts. Undeclared columns are discarded at ingest and later operations on them fail with UNDECLARED_FIELD.
`latitude_field`	No	Latitude column. Defaults accept case-insensitive GIS aliases latitude/lat (including LAT). Override for non-standard headers (e.g. Address 1: Latitude). Explicit values win over aliases.	latitude
`map_session_id`	No	Open map session (msess_...) from get_map_visualization. Its Territory Solution is the input; omit ts_handle when set.
`min_confidence`	No
`accounts_handle`	No	Required. upload_handle (aup_...) from request_account_upload. Single-use: ingest claims it.
`force_regeocode`	No	When true, ignore existing coordinates and geocode addresses. Also confirms intentional address geocoding when unused numeric lat/lon-like columns are present (skips needs_coordinate_fields guard).
`grouping_fields`	No	Declared columns used to group accounts (e.g. account_build grouping_field candidates). Declared fields are the retention contract: the compact TS keeps only id, coordinates, label, and declared fields; undeclared columns are discarded at ingest.
`longitude_field`	No	Longitude column. Defaults accept case-insensitive GIS aliases longitude/lon/lng/long (including LON). Override for non-standard headers. Explicit values win over aliases.	longitude
`workload_fields`	No
`dwell_time_field`	No	Canonical per-account dwell column on point features. Pair with workload_fields unit metadata when values are in hours.
`service_zip_field`	No	Contractor column listing served ZIPs, comma-separated, for coverage.rule=zip_list. Retained like a declared column.
`visit_frequency_field`	No	Canonical numeric visits-per-cycle column on point features. Agent-resolved; MCP validates presence and persists on point-layer metadata. Without one, MCP defaults each account to one visit per cycle.
`accept_suboptimal_geocodes`	No	When true (default for ingest), accept provider suboptimal geocodes (e.g. ZIP centroids) so address-only rows become points. Set false to require optimal/point-address matches only.

Output Schema

Name	Required	Description
`ok`	Yes
`error`	No	Present when ok is false.
`result`	No	Present when ok is true.
`warnings`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed31 schema fields changedNov 1, 2026

addedInput schema / $defs

Added value: +{
+  "RepoShape1": {
+    "additionalProperties": false,
+    "properties": {
+      "field": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "label": {
+        "type": "string"
+      },
+      "role": {
+        "description": "Optional semantic role for workload columns. Agents should set visit_frequency or dwell_time when declaring canonical workload inputs.",
+        "type": "string"
+      },
+      "type": {
+        "enum": [
+          "number",
+          "integer",
+          "string",
+          "boolean"
+        ],
+        "type": "string"
+      },
+      "unit": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "field"
+    ],
+    "type": "object"
+  }
+}

addedInput schema / properties / accept_suboptimal_geocodes / description

Added value: +"When true (default for ingest), accept provider suboptimal geocodes (e.g. ZIP centroids) so address-only rows become points. Set false to require optimal/point-address matches only."

addedInput schema / properties / accounts_handle / description

Added value: +"Required. upload_handle (aup_...) from request_account_upload. Single-use: ingest claims it."

addedInput schema / properties / capacity_field / description

Added value: +"Numeric contractor column holding capacity (e.g. jobs per month). Retained like a declared column."

addedInput schema / properties / display_fields / description

Added value: +"Declared columns shown in Map Component point callouts. Undeclared columns are discarded at ingest and later operations on them fail with UNDECLARED_FIELD."

addedInput schema / properties / dwell_time_field / description

Added value: +"Canonical per-account dwell column on point features. Pair with workload_fields unit metadata when values are in hours."

addedInput schema / properties / force_regeocode / description

Added value: +"When true, ignore existing coordinates and geocode addresses. Also confirms intentional address geocoding when unused numeric lat/lon-like columns are present (skips needs_coordinate_fields guard)."

addedInput schema / properties / grouping_fields / description

Added value: +"Declared columns used to group accounts (e.g. account_build grouping_field candidates). Declared fields are the retention contract: the compact TS keeps only id, coordinates, label, and declared fields; undeclared columns are discarded at ingest."

addedInput schema / properties / id_field / description

Added value: +"Unique business key column. Duplicated label/name columns fail with blocked_by=needs_unique_row_id. With the default row_id and no unique column, the server synthesizes row-1, row-2, … when that column is absent."

addedInput schema / properties / label / description

Added value: +"Legend name for the point layer. Omitted: the point_layer id in title case (accounts is 'Accounts', schools_conus is 'Schools Conus')."

addedInput schema / properties / latitude_field / description

Added value: +"Latitude column. Defaults accept case-insensitive GIS aliases latitude/lat (including LAT). Override for non-standard headers (e.g. Address 1: Latitude). Explicit values win over aliases."

addedInput schema / properties / layer_role / description

Added value: +"contractors marks the supply side of a service network (contractor, vendor, service provider) for analyze_network_coverage."

addedInput schema / properties / longitude_field / description

Added value: +"Longitude column. Defaults accept case-insensitive GIS aliases longitude/lon/lng/long (including LON). Override for non-standard headers. Explicit values win over aliases."

addedInput schema / properties / map_session_id / description

Added value: +"Open map session (msess_...) from get_map_visualization. Its Territory Solution is the input; omit ts_handle when set."

changedInput schema / properties / metric_fields / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "default": [],
+    "items": {
+      "$ref": "#/$defs/RepoShape1"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / metric_fields / description

Added value: +"Agent-confirmed business metric columns (for example revenue, sales, units) to persist on point-layer metadata for downstream build/analyze tools."

removedInput schema / properties / metric_fields / title
```
Removed value: -"Metric Fields"
```

removedInput schema / properties / rows

Removed value: -{
-  "anyOf": [
-    {
-      "items": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "type": "array"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Rows"
-}

addedInput schema / properties / search_fields / description

Added value: +"Declared columns searchable in the Map Component. Undeclared columns are discarded at ingest and later operations on them fail with UNDECLARED_FIELD."

addedInput schema / properties / service_zip_field / description

Added value: +"Contractor column listing served ZIPs, comma-separated, for coverage.rule=zip_list. Retained like a declared column."

addedInput schema / properties / tier_field / description

Added value: +"Contractor column holding the network tier (e.g. Preferred). Retained like a declared column."

addedInput schema / properties / trade_field / description

Added value: +"Contractor column naming the trade(s) served (e.g. HVAC; comma-separated for several). Retained like a declared column."

removedInput schema / properties / ts

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Ts"
-}

addedInput schema / properties / ts_handle / description

Added value: +"Territory Solution reference (tsh_...) from a build, ingest_accounts, import_geojson, import_designer_project, or get_map_visualization; Territory Solutions are not accepted inline."

addedInput schema / properties / visit_frequency_field / description

Added value: +"Canonical numeric visits-per-cycle column on point features. Agent-resolved; MCP validates presence and persists on point-layer metadata. Without one, MCP defaults each account to one visit per cycle."

changedInput schema / properties / workload_fields / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "default": [],
+    "items": {
+      "$ref": "#/$defs/RepoShape1"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / workload_fields / title
```
Removed value: -"Workload Fields"
```
removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / properties

Added value: +{
+  "error": {
+    "description": "Present when ok is false.",
+    "properties": {
+      "ask_user": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "code": {
+        "type": "string"
+      },
+      "details": {
+        "type": "object"
+      },
+      "do_this_next": {
+        "type": "object"
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "ok": {
+    "type": "boolean"
+  },
+  "result": {
+    "description": "Present when ok is true.",
+    "properties": {
+      "created_at": {
+        "type": "string"
+      },
+      "do_this_next": {
+        "type": "object"
+      },
+      "estimated_remaining_ms": {
+        "type": "integer"
+      },
+      "estimated_start_ms": {
+        "type": "integer"
+      },
+      "expires_at": {
+        "type": "string"
+      },
+      "job_id": {
+        "type": "string"
+      },
+      "next_action": {
+        "type": "string"
+      },
+      "next_poll_at": {
+        "type": "string"
+      },
+      "phase": {
+        "type": "string"
+      },
+      "poll_interval_ms": {
+        "type": "integer"
+      },
+      "poll_loop": {
+        "type": "object"
+      },
+      "progress": {
+        "type": "number"
+      },
+      "queue_depth": {
+        "type": "integer"
+      },
+      "queue_lane": {},
+      "queue_position": {
+        "type": "integer"
+      },
+      "recommended_poll_delay_ms": {
+        "type": "integer"
+      },
+      "required_input": {
+        "type": "object"
+      },
+      "result_resource_uri": {
+        "type": "string"
+      },
+      "sleep_ms": {
+        "type": "integer"
+      },
+      "status": {
+        "type": "string"
+      },
+      "status_resource_uri": {
+        "type": "string"
+      },
+      "task_id": {
+        "type": "string"
+      },
+      "terminal": {
+        "type": "boolean"
+      },
+      "tool_name": {
+        "type": "string"
+      },
+      "total": {
+        "type": [
+          "null",
+          "number"
+        ]
+      },
+      "user_cancelled": {
+        "type": "boolean"
+      }
+    },
+    "type": "object"
+  },
+  "warnings": {
+    "items": {
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  }
+}

addedOutput schema / required
```
Added value: +[
+  "ok"
+]
```

removedOutput schema / title

Removed value: -"ingest_accountsDictOutput"

Changed5 schema fields changedOct 16, 2026

addedInput schema / properties / capacity_field

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Capacity Field"
+}

addedInput schema / properties / layer_role

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "accounts",
+        "contractors"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Layer Role"
+}

addedInput schema / properties / service_zip_field

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Service Zip Field"
+}

addedInput schema / properties / tier_field

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Tier Field"
+}

addedInput schema / properties / trade_field

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Trade Field"
+}

Changed3 schema fields changedOct 12, 2026
- addedInput schema / properties / label / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / label / default
```
Previous value: -"Accounts"New value: +null
```
- removedInput schema / properties / label / type
```
Removed value: -"string"
```

Changed1 schema field changedOct 9, 2026

removedInput schema / properties / guidance_handle

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Guidance Handle"
-}

First observedSep 29, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses concrete failure semantics: geocode quota exceeded fails the whole ingest, unused coordinate-like columns trigger CLARIFICATION_REQUIRED, duplicate ids return needs_unique_row_id, undeclared columns fail later with UNDECLARED_FIELD, and the handle is single-use. The 100,000-row cap and declared-column retention contract are also stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the upstream-handle requirement, then error modes and contractor variant. It is dense and parenthetical-heavy in one long block, but nearly every clause carries operational information rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 27-parameter mutation tool, it covers the major traps (handle provenance, coordinate detection, id uniqueness, column retention, quota failure) and an output schema exists for return values. Minor gaps remain around use_cache, min_confidence, and region/country hints, but nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 74%, and the description adds real meaning: coordinate alias handling (lat/lng) versus latitude_field/longitude_field overrides, id_field default row_id with synthesized row-N keys, force_regeocode's dual role in bypassing the coordinate guard, and the retention contract for declared fields. Some parameters (use_cache, min_confidence, region_hint, country_hint, label_field) are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: loads account rows (CRM/CSV/spreadsheet) as point data on a named point layer of the Territory Solution, with geocoding of rows lacking coordinates. This is clearly distinguishable from siblings like import_geojson or seed_build.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly scopes inputs: rows come only via accounts_handle from request_account_upload, and its suggested_ingest carries these args. Also routes contractor loading to layer_role=contractors with analyze_network_coverage. It does not explicitly contrast with import_geojson or seed_build as alternatives, so not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All EasyTerritory MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?