Tools

Four tools, modelled on jobs rather than on the ~30 query parameters of the render API. The full parameter surface is still reachable — see extra — but a model does not have to wade through it to make a map.

Two of them make maps, create_map and add_layers, and both return the same thing:

Field	What it is
svg_url	The map. Embeddable, permanent, and the handle add_layers accepts.
png_url	The same map as PNG.
editor_url	The map loaded in app.maproll.io, ready to edit.
embed	A ready <img> tag.
warnings	Non-fatal problems, as strings. Unrecognised region ids, dropped routes, clipped markers.

The rendered PNG also comes back as an image content block, so the assistant can see what it made.

create_map

Purpose. Makes a map from scratch: a geography, plus whatever data, styling and framing you give it.

When to use it. Any first map in a conversation, and any time the geography, the data or the theme changes. To add to a map that already exists, use add_layers instead — rebuilding from scratch loses everything you are not restating.

Inputs

Required:

Argument	Type	Notes
scope	string	The geography. world, one of 16 group scopes (EU, NATO, G7, ASEAN, …), or a country scope for its subnational regions (RO, US, FR, …). Case-sensitive; see the scopes list.

Everything else is optional:

Argument	Type	Notes
values	array of { id, value?, color?, category? }	Region data. Max 5000 entries.
highlight	string[]	Region ids to paint in the theme accent, with no values behind them. Max 5000.
title	string	Max 120 characters.
subtitle	string	Max 160 characters.
legendTitle	string	Max 120 characters. Usually the unit.
legend	boolean	Show or hide the legend.
theme	enum	dark, dark-blue, dark-mono, light, light-blue, light-mono.
colorScale	enum	sequential, diverging, categorical.
classification	enum	quantile, jenks, equal, custom.
breaks	number[]	Explicit class boundaries, 1–20 of them.
projection	enum	naturalEarth1, albersUsa, conicConformal, mercator, equalEarth.
legendLayout	enum	vertical, horizontal, continuous.
width, height	integer	1–8000 pixels.
bbox	string	"minLon,minLat,maxLon,maxLat" — crop to a window instead of fitting the scope.
graticule, northArrow, scaleBar, attribution	boolean	Map furniture.
labels	"ISO" or string[]	Region labels: ISO codes on every region, or an explicit list. See region labels.
extra	record	Passed to the render API verbatim. See extra.

Region data arrives structured, not as the packed data= string. Each entry in values takes one of four forms, matching the data grammar:

Form	Produces
{ id, value }	A choropleth, binned by classification and coloured by colorScale.
{ id, value, color }	The same, with an explicit fill overriding the scale for that region.
{ id, color }	Flat paint with no value behind it. Pair with legend: false.
{ id, category }	A qualitative bucket. Selects a categorical scale and names the bucket in the legend.

Example

{
  "scope": "world",
  "title": "Coffee consumption per capita",
  "subtitle": "kg per person per year",
  "legendTitle": "kg / person",
  "theme": "dark",
  "width": 900,
  "values": [
    { "id": "FI", "value": 12 },
    { "id": "NO", "value": 9.9 },
    { "id": "US", "value": 4.2 }
  ]
}

For a map about which regions rather than how much, use highlight instead of values:

{ "scope": "EU", "highlight": ["RO", "DE", "FR"], "legend": false }

Warnings and errors

• Numeric values and text categories cannot appear in the same map. The server throws and names the offending ids, rather than letting the renderer return a 400 the assistant has to reverse-engineer. Pick one: magnitudes, or buckets.
• Unrecognised region ids are skipped, not fatal. They come back in warnings, and the rest of the map renders. A silently missing country is almost always a wrong id — RO-B in a world scope, or UK for GB.
• An unknown scope fails the render. Scope names are case-sensitive; describe_options with kind: "scopes" lists them.
• Invented enum values render nothing and report nothing. A theme or icon name that does not exist is not an error. Check with describe_options rather than guessing.
• Over 5000 entries in values or highlight is rejected by the schema, before any render happens.

extra

Anything documented in these pages but without a dedicated field — patterns, annotations, proportional, labelMinArea — passes through extra verbatim:

{ "scope": "world", "extra": { "labelMinArea": 400, "patterns": "DE:dots" } }

One thing extra cannot do is remove the wordmark from an unkeyed render: src=mcp without a key forces it on and ignores logo=false. See the wordmark.

add_layers

Purpose. Takes a map URL and adds to it. Everything already on the map is kept, so this is how a map is built up over several turns rather than rebuilt from scratch each time.

When to use it. Whenever the previous map is right and something is missing — markers, routes, proportional circles, hatching, hover text. If the data or the geography itself is wrong, go back to create_map.

Inputs

Required:

Argument	Type	Notes
map	string	A map URL returned by an earlier create_map or add_layers call.

Optional, and at least one of them is the point of the call:

Argument	Type	Notes
markers	array of { lat, lon, icon?, sidc?, label?, labelPosition?, size? }	Max 1000. labelPosition is top, bottom, left or right.
routes	array of { from, to, color?, width?, style?, arrow?, sea? }	Max 500. style is solid or dashed. Endpoints are ISO codes or lat,lon.
proportional	array of { id, value, color? }	Circles sized by value on top of the fill.
patterns	array of { id, pattern }	stripes, stripes-diagonal, dots, crosshatch, solid-outline.
annotations	array of { id, text }	Hover text per region. text max 200 characters.
labels	"ISO" or string[]	Same as on create_map.

icon and sidc are mutually exclusive on a marker: one draws from the 30-icon library, the other renders a MIL-STD-2525 symbol.

Example

{
  "map": "https://api.maproll.io/map.svg?scope=world&theme=dark",
  "markers": [
    { "lat": 44.17, "lon": 28.65, "icon": "anchor", "label": "Constanța" }
  ],
  "routes": [
    { "from": "31.23,121.47", "to": "51.92,4.48", "sea": true, "arrow": true }
  ]
}

sea: true follows the maritime network through Suez, Panama and Malacca instead of drawing a great circle over land — see routes.

Warnings and errors

• It appends. Pair-list parameters — proportional, patterns, annotations — merge into what the URL already carries rather than replacing it. Sending the same list twice duplicates nothing but wastes a turn; sending a shorter list does not remove anything.
• map must be a maproll map URL. Anything else is rejected. Use the svg_url from the previous response, not a URL retyped from memory.
• A sea route with no reachable lane is dropped. Endpoints further than 500 km from the maritime network — landlocked pairs, mostly — produce a warning and no line, and the render still succeeds.
• Off-screen markers vanish silently. A point outside the projection's visible domain produces no output and no error, which usually means the coordinates are wrong. Resolve them with find_places first.
• Caps are enforced by the schema: 1000 markers, 500 routes.

find_places

Purpose. Resolves a place name to real coordinates and the id maproll uses.

When to use it. Before placing any marker or lat,lon route endpoint. This is the one thing an assistant genuinely cannot do from memory: recalled coordinates are routinely wrong by degrees, and the renderer will happily draw the marker wherever it is told. It is also the way to turn a spreadsheet's country names into the ISO ids values and highlight expect.

Inputs

Argument	Type	Notes
query	string	Required. At least 2 characters.
kind	enum	country, region, city, airport. Omit to search all four.
limit	integer	1–25. Default 10.

Output

Each hit carries name, kind, id, lat, lon, country, countryId, region and regionId. The id is the identifier the render API wants: ISO 3166-1 alpha-2 for countries, ISO 3166-2 for regions, IATA for airports.

{ "query": "Constanța", "kind": "city" }

Warnings and errors

• A query under 2 characters is rejected by the schema.
• No hits is an empty result, not an error. Usually a spelling or a diacritic; try the local name and the English one.
• Ambiguous names return several hits. There are many Springfields. Pick on country and region, do not assume the first row.

describe_options

Purpose. Returns the exact accepted values for one catalog.

When to use it. Before using any enum the assistant is not certain of. An invented theme or icon name renders nothing and reports no error, so checking beats guessing.

Inputs

Argument	Type	Notes
kind	enum	Required. scopes, themes, icons, projections, patterns or grammar.

Output

The catalog as text: every scope, the 6 themes, 30 marker icons in 8 groups, 5 projections, 5 pattern fills, or — for grammar — how region data, markers and routes are encoded.

{ "kind": "icons" }

Warnings and errors

• kind must be one of the six. There is no catalog of, say, colour scales; those are enumerated in create_map's schema.
• The same content is published as resources. This tool exists for clients that do not read resources; if yours does, reading maproll://catalog/icons costs no tool call.