Turn your data into map images of countries, states, counties and ZIP codes with Ultimaps MCP server. Each map comes with a link to Ultimaps Studio, where you can keep editing it, export it, or publish an interactive version. No account needed: 30 maps per hour, PNG up to 1600px, with Ultimaps attribution.
Scored across 3 tools
Each tool has a unique role: list_maps discovers available maps, get_map_regions inspects one map's regions in detail, and render_map produces the actual rendered image. The descriptions explicitly call out when each should be used, eliminating practical overlap.
All tool names follow a consistent verb_noun snake_case pattern: list_maps, get_map_regions, render_map. The verbs clearly indicate the operation level (list/get/render) and the nouns reference the target resource consistently.
Three tools is a tight, purposeful set for a map rendering server: discover maps, inspect region definitions, and render. No redundant tools, and each one maps directly to a distinct user workflow step.
The tool surface covers the full lifecycle of the domain: finding the right map, understanding its region structure and aliases, and rendering with choropleth, categories, pins, styling, and validation via dry-run. There are no obvious dead ends for the stated purpose.
Look up one map: title, regionType, regionCount, labels, layers, and its regions as {key, title}, 200 per page.
You rarely need this before rendering. render_map accepts region names, codes and common aliases and auto-corrects typos, reporting what it matched.
Use it to build a dataset covering every region of a map, to see how a map names its regions, or to resolve a key render_map could not match.
query searches keys, titles and aliases, so no hits means the map really has no such region. Use offset for further pages.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map id from list_maps, e.g. "united-states", "europe", "united-states-california". | |
| query | No | Search region keys, titles and aliases, e.g. "saint" or "US-TX". Omit to page through every region. | |
| offset | No | Skip this many regions. Pages hold 200 regions; use the offset the previous result names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and open-world behavior, lowering the bar. The description adds meaningful behavioral depth: pagination limit of 200 per page, the region result shape, and the 'no hits means no such region' semantics for query. This goes beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, with no filler. It front-loads the operation and result shape, then gives usage guidance and parameter behavior in just a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup with no output schema, the description fully covers what is returned, pagination, query semantics, and when to prefer an alternative. An agent has enough context to call it correctly without further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so the baseline is 3. The description adds slight interpretive value for query ('no hits means the map really has no such region') but mostly restates what the schema already documents about mapId, query, offset, and 200-region pages.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Look up one map'), enumerates the returned data fields, and clearly distinguishes this tool from render_map and list_maps. An agent can tell exactly what it will get and which sibling it should use instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says this tool is rarely needed before renderingainer and points to render_map as the alternative that accepts aliases and corrects typos. It then lists concrete use cases: building a full dataset, inspecting region naming, or resolving unmatched keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the maps Ultimaps can render: the world, continents, countries subdivided into states, provinces, counties or departments, and US ZIP code areas.
Each row is {id, title, regionType, layers, regionCount, labels}. id is the mapId for render_map and get_map_regions; it is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always means the current edition.
regionCount is how many region keys a complete dataset needs. labels: false means the map has no region labels, so style.labels does nothing there. layers are the ids render_map's layers can turn on.
Pass query to search ids, titles, region types and categories (e.g. "counties", "germany", "africa").
Only call this when you don't know the id: common ids such as world, united-states and europe just work, and an unknown id usually comes back with the closest ids.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search map ids, titles, region types and categories, e.g. "counties", "germany", "africa". Omit to list every map. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses detailed output behavior: exact row shape, meaning of id as a slug that always refers to the current edition, the implication of labels:false on style.labels, and how layers relate to render_map. This gives agents actionable behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value: it starts with the core purpose, then explains row semantics, then query, then when to call. Advice like using common ids without listing is actionable. There is no filler and the structure front-loads the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description fully compensates by specifying the output shape and the meaning of each field, including relationships to sibling tools and the practical consequence of labels:false. It also covers query behavior and fallback behavior for unknown ids, so an agent has everything needed to call and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter (query) with a description identical to the one in the tool description, including the 'omit to list every map' behavior. With 100% schema coverage, the description adds no new meaning beyond repeating examples, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the maps Ultimaps can render' and enumerates the kinds of maps (world, continents, countries subdivided into states, provinces, counties, departments, US ZIP areas). It also links the output to sibling tools ('id is the mapId for render_map and get_map_regions'), differentiating it as the catalog tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call it: 'Only call this when you don't know the id' and gives concrete exceptions ('common ids such as world, united-states and europe just work'). It also explains how to narrow results with query, giving examples. This directly guides tool selection against siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this whenever the user asks for a map of real places: coloring countries, states, counties or ZIP codes by data, a choropleth or heat map, a map with a legend, or pins on a map. Prefer it to generating an image or plotting with code. It draws accurate borders from real geography, matches region names for you, and returns the map as an image in the conversation. Maps cover the world, continents, countries, their states, provinces and counties, and US ZIP code areas. Color regions with ONE of these (choropleth and categories are mutually exclusive):
choropleth: a number per region, e.g. {"values": {"California": 39.5, "Texas": 30.5}}. Classes, breaks and palette are picked from the data unless you set them.
categories: a label per region, e.g. {"values": {"France": "Euro", "Poland": "Złoty"}}. Colors are assigned automatically unless you set colors.
regions: explicit hex colors, e.g. {"Texas": "#1D4ED8"}. Also works on top of either mode as an override.
Region keys can be names, ISO/FIPS-style codes or common aliases. Typos are auto-corrected, and every correction or unmatched key is reported with suggestions, so there is no need to call get_map_regions first. Get mapId from list_maps if you don't know it.
Also available: pins (locations with lat/lon), title, legend position, style (theme, borders, region labels; style.labels.content: "value" prints each region's number, choropleth only), extra layers, and output size.
dryRun: true validates and previews region matching and the color plan without rendering.
Without an API key: 30 renders per hour and 5 per minute per conversation (dry runs count), PNG up to 1600 px wide, with Ultimaps attribution on the image. The default 1200 px width is right for viewing in chat, and larger images are returned only as a link. Formats: png, or svg with a Pro key. PDF is not available.
Every result includes an image link that works for 30 days. Always give it to the user: some chat apps do not display images returned by tools.
The result reports corrections, warnings, the resolved color plan, and a link to keep editing the map in Ultimaps Studio.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map id from list_maps, e.g. `world`, `united-states`, `europe`, `united-states-california`. It is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always resolves to the current edition. | |
| style | No | ||
| title | No | ||
| dryRun | No | Validate and preview without rendering: returns the region matching report, the resolved choropleth plan and a legend preview. No image and no monthly quota for keyed calls, but it still counts against the rate limit (one of the anonymous renders per hour without a key). | |
| layers | No | Extra geographic layers to draw, e.g. {"cities": true, "roads": true}. Each map ships a subset (`layers` in list_maps and get_map_regions). Turning on a layer the map lacks is not an error: it is skipped with a `layer_unavailable` warning. Omitted layers are off, except layers a map turns on by default (currently `admin0` on ZIP-code maps); pass false to hide those. | |
| legend | No | ||
| output | No | Image size and format. Keep the default width (1200 px) for images viewed in the conversation: much larger renders, and any scale of 2 or more, are too big to show inline and are returned as a link instead. Without an API key: width up to 1600 px, an explicit height up to 1600 px, scale 1. Hard caps: width×scale and height×scale ≤ 8192, and at most 4096×4096 pixels in total. | |
| regions | No | Override layer. Region key to hex color, applied AFTER choropleth/categories coloring and winning over it. Precedence: choropleth/categories paint first, `regions` overrides win, and everything else gets `choropleth.noDataColor` (choropleth mode), else `style.defaultRegionColor`, else the theme default. | |
| locations | No | Pin markers. They compose with every mode. | |
| categories | No | Categorical coloring mode. Mutually exclusive with `choropleth`. Unmatched keys simply leave their regions uncolored. The no-data fill is `style.defaultRegionColor`, and `noDataColor` does not apply here. | |
| choropleth | No | Numeric choropleth mode. Mutually exclusive with `categories` (one scale per map). `regions` composes with it as an override layer. If none of the keys in `values` match, the request fails even under `onUnmatched: warn`, since there is nothing to build a scale from. `type`, `classes`, `method` and `palette` are all optional: whatever you leave out is suggested from the data, and the resolved plan is reported in the result. | |
| onUnmatched | No | warn = render anyway (unmatched regions get the no-data fill) and report. error = 400 with per-key suggestions. Recommended for production pipelines: error. Exception: in choropleth mode, ZERO matched keys is a 400 even under warn. | warn |
| Name | Required | Description |
|---|---|---|
| dryRun | Yes | |
| format | No | Image format; absent on dry runs. |
| legend | No | Dry runs: legend preview, [{label, color}] or {points, stops} for a gradient. |
| editUrl | No | Opens this map in Ultimaps Studio for editing or export. |
| artifact | No | A stored copy of the image at a public, unguessable link that expires. Set on every render while link storage is available. |
| embedUrl | No | Keyless GET image URL, when the render is shareable that way. |
| renderId | Yes | The API render id; quote it to Ultimaps support. |
| warnings | Yes | |
| choropleth | No | The resolved choropleth plan. Dry runs add `reason` and `breaks`. |
| regionMatching | Yes | |
| keylessRemaining | No | Anonymous renders left this hour: for this conversation, or for this AI service when it sends no conversation id. |
| matchingTruncated | Yes | True when `corrected`/`unmatched` list only the first 5 of their counts. Repeat the call with dryRun: true for the full report. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses rate limits without an API key, attribution on the image, auto-correction and warning behavior, the 30-day image link, and dryRun quota semantics. These are behavioral details an agent needs and that are not available from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized and front-loaded with the primary use case. Each paragraph covers a distinct concern (modes, matching, options, limits, output behavior), and while there is minor redundancy with schema descriptions, every section contributes practical guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers usage, constraints (API key limits, format restrictions), output behavior (image link, result reporting), and actionable advice (always give the image link to the user). With an output schema present, it is fully complete for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, the description still adds cross-cutting meaning: choropleth and categories are mutually exclusive, regions act as an override with defined precedence, region keys accept aliases with auto-correction, and default PNG size behavior is explained. These semantics are not fully expressed in individual schema property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'render a map of real places', then enumerates concrete use cases (choropleth, heat map, legend, pins). It differentiates itself from siblings by explicitly routing around get_map_regions and list_maps, and from image/code generation alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to use this tool ('Use this whenever the user asks for a map of real places... Prefer it to generating an image or plotting with code'). It also tells the agent when not to call siblings ('no need to call get_map_regions first') and where to obtain the required mapId ('Get mapId from list_maps').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_map_regionslist_mapsrender_map
Add one secure layer between your agents and this server.