Skip to main content
Glama

cluster

Group stops into balanced geographic clusters, so a day too large for one optimisation can be optimised one cluster at a time. This is the front half of the recipe for a thousand-stop day: cluster here, then call optimise_routes per cluster, where the routing engine's own matrix decides the visiting order. IMPORTANT, this is STRAIGHT-LINE clustering. Distances are measured between coordinates, not along the road network: no road, river, motorway junction or one-way system is consulted, and two stops either side of an estuary look adjacent. That makes it the right tool for deciding which stops belong TOGETHER and the wrong one for deciding what ORDER to visit them in. The answer carries a basis sentence saying exactly this; show it, so a centroid is never read as a plan. Provide locations ([{id, lat, lon, load?}], ids unique, at most 5,000) and EXACTLY ONE of clusters (how many groups, balanced by stop count), max_cluster_locations or max_cluster_load (a per-cluster ceiling the count is derived from). Optional territories keep a cluster from straddling a round: each is clustered on its own, and so are the stops inside none of them. Optional seed (default 42) drives the seeding, the same request with the same seed always returns the same clusters, on every deployment, so a re-run is a re-run. Returns each cluster's member ids, count, summed load, centroid and territory, plus a balance block naming the constraint applied and whether it had to be relaxed to place every stop: a load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count. Requires the MapMap gateway.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "locations": "<locations>"
    },
    "name": "cluster"
  }
}

Input Schema

NameRequiredDescriptionDefault
seedNoSeed for the k-means++ seeding (default 42). The same request with the same seed always returns the same clusters, on every deployment.
clustersNoHow many clusters to produce, balanced by stop count. Give exactly one of `clusters`, `max_cluster_locations` or `max_cluster_load`.
locationsYesThe stops to group. Ids must be unique; at most 5,000.
territoriesNoOptional territories. Given, no cluster straddles one: each territory is clustered on its own, and so are the stops inside none of them.
max_cluster_loadNoAt most this much summed `load` per cluster; the cluster count is derived from it. A load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count, the response says so rather than pretending.
max_cluster_locationsNoAt most this many stops per cluster; the cluster count is derived from it.

Output Schema

NameRequiredDescriptionDefault
basisYesThe method statement: this is STRAIGHT-LINE clustering. Distances are between coordinates, not along roads, two stops either side of an estuary look adjacent. Show it. It is the sentence that stops a centroid being read as a plan.
balanceYesThe constraint applied, the largest cluster produced, and whether the ceiling had to be relaxed to place every stop.
clustersYesThe clusters: each with its `id`, member `locations` (your ids), `count`, summed `load`, `centroid` and the `territory` it belongs to.
parametersYesThe seed, the cluster count, the locations seen, how many territories were used, the iterations run and whether it converged.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / $defs / TerritorySpec / additionalProperties
      Added value: +false
  2. Changed4 schema fields changed
    • changedInput schema / $defs / ClusterLocationSpec / properties / load / description
      Previous value: -"Optional weight — parcels, kilograms, litres, minutes of service.\nSummed per cluster and reported; constrains the clustering only\nunder `max_cluster_load`."New value: +"Optional weight, parcels, kilograms, litres, minutes of service.\nSummed per cluster and reported; constrains the clustering only\nunder `max_cluster_load`."
    • changedInput schema / $defs / TerritorySpec / properties / polygon / description
      Previous value: -"The outer ring as GeoJSON `[lon, lat]` positions — longitude\nFIRST. Closed or open; an unclosed ring is closed for you."New value: +"The outer ring as GeoJSON `[lon, lat]` positions, longitude\nFIRST. Closed or open; an unclosed ring is closed for you."
    • changedInput schema / properties / max_cluster_load / description
      Previous value: -"At most this much summed `load` per cluster; the cluster count is\nderived from it. A load ceiling with lumpy loads is a bin-packing\nproblem and may have no solution at the derived count — the\nresponse says so rather than pretending."New value: +"At most this much summed `load` per cluster; the cluster count is\nderived from it. A load ceiling with lumpy loads is a bin-packing\nproblem and may have no solution at the derived count, the\nresponse says so rather than pretending."
    • changedOutput schema / properties / basis / description
      Previous value: -"The method statement: this is STRAIGHT-LINE clustering. Distances\nare between coordinates, not along roads — two stops either side of\nan estuary look adjacent. Show it. It is the sentence that stops a\ncentroid being read as a plan."New value: +"The method statement: this is STRAIGHT-LINE clustering. Distances\nare between coordinates, not along roads, two stops either side of\nan estuary look adjacent. Show it. It is the sentence that stops a\ncentroid being read as a plan."
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the straight-line distance model and its estuary failure mode, seed determinism across deployments, the 5,000 id ceiling, uniqueness requirements, and that the balance block may report a relaxed constraint rather than a feasible one. It also states the gateway requirement, which is an auth/dependency fact an agent needs before calling.

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 purpose and hand-off before the caveat, which is the right order for an agent skimming. It is dense but not padded; the only waste is restating parameter mechanics (ids unique, at most 5,000, seed default 42) that the schema already documents at 100% coverage.

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

Completeness5/5

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

For a six-parameter clustering tool with no annotations, the description covers the decisions an agent actually has to make: which constraint to pass, how territories partition the work, determinism on re-run, and what a returned centroid does and does not mean. The return-value prose slightly duplicates the output schema but is justified by the misinterpretation risk it guards against.

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 100%, so baseline is 3, but the description adds cross-parameter meaning the schema states only piecemeal: EXACTLY ONE of `clusters`/`max_cluster_locations`/`max_cluster_load` must be supplied, and `load` constrains clustering only under `max_cluster_load` (otherwise it is merely summed). It does not add format detail beyond the schema, keeping it off a 5.

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 ("group stops into balanced geographic clusters") and immediately bounds the scope: it is the front half of a two-step recipe, with `optimise_routes` doing ordering. An agent can distinguish it from matrix and optimise_routes without opening any schema.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use sequence ("cluster here, then call `optimise_routes` per cluster") and an explicit when-not-to-use ("the wrong one for deciding what ORDER to visit them in"). It also names the sibling to hand off to, so routing is unambiguous.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources