Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Difference of Polygons

difference_tool
Read-onlyIdempotent

Subtract one polygon from another to compute exclusion zones or areas in zone A not covered by zone B, returning null if fully covered.

Instructions

Subtract one polygon from another, returning the area in polygon1 that is not covered by polygon2. Useful for computing exclusion zones, finding uncovered service areas, or "what is in zone A but not zone B?". Returns null geometry if polygon2 fully covers polygon1. Works offline without API calls. INPUT SHAPE: polygon1 and polygon2 are each an array of rings; each ring is an array of [lng, lat] pairs. When chaining with isochrone_tool, extract feature.geometry.coordinates from each isochrone Feature (with polygons=true).

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": {
      "polygon1": "<polygon1>",
      "polygon2": "<polygon2>"
    },
    "name": "difference_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
polygon1YesThe polygon to subtract from
polygon2YesThe polygon to subtract

Output Schema

NameRequiredDescriptionDefault
geometryYesGeoJSON geometry of the remaining area (polygon1 minus polygon2), or null if polygon2 fully covers polygon1
mapboxRenderNoMap-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.
has_differenceYesWhether any area remains after subtracting polygon2 from polygon1

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.18.1
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / polygon1 / items / description
      Added value: +"A closed linear ring: 4+ [longitude, latitude] coordinate pairs where the first and last pair are identical (e.g. [[-77, 38], [-76, 38], [-76, 39], [-77, 39], [-77, 38]])."
    • addedInput schema / properties / polygon1 / items / minItems
      Added value: +4
    • addedInput schema / properties / polygon2 / items / description
      Added value: +"A closed linear ring: 4+ [longitude, latitude] coordinate pairs where the first and last pair are identical (e.g. [[-77, 38], [-76, 38], [-76, 39], [-77, 39], [-77, 38]])."
    • addedInput schema / properties / polygon2 / items / minItems
      Added value: +4
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +{}
    • addedOutput schema / properties / mapboxRender
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Map-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.",
      +  "properties": {
      +    "ref": {
      +      "description": "Server-side payload reference. Pass to `render_map_tool` via `payload_refs: [\"<this ref>\"]` to display the data on a live Mapbox GL JS map, or, in ChatGPT Desktop, to the `redraw_map` tool of the open Mapbox map.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "ref"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.12.6

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the null-geometry result when polygon2 fully covers polygon1, and that the operation runs offline without API calls. It stops short of documenting invalid-geometry handling or degenerate/self-intersecting ring behavior.

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 verb and result semantics, then edge case, then input shape and chaining. The INPUT SHAPE sentence partially duplicates the 100%-covered schema, which is the main wasted wording, but the passage is short and every other sentence earns its place.

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 two-required-parameter geometry operation with an output schema and full annotations, this covers purpose, result edge case, offline behavior, and input wiring. Minor omissions (invalid-ring behavior, multi-ring holes semantics for polygon2) are the only remaining gaps.

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 the ring structure and coordinate ordering are already documented, and the INPUT SHAPE paragraph largely restates that. The added value is the chaining instruction to extract `feature.geometry.coordinates` from isochrone Features, which is meaning the schema cannot convey.

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 ('Subtract one polygon from another') and defines the result precisely as 'the area in polygon1 that is not covered by polygon2.' That definition alone separates it from sibling set operations like union_tool and intersect_tool without opening either schema.

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?

Gives concrete use cases (exclusion zones, uncovered service areas, 'what is in zone A but not zone B') and explicitly describes chaining with isochrone_tool, including the `polygons=true` prerequisite. It does not name the sibling alternatives it replaces (intersect_tool, union_tool) or state when-not to use it, which keeps it below a 5.

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