Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Category Search Tool

category_search_tool
Read-onlyIdempotent

Find all places matching a category such as museums, coffee shops, or EV chargers, returning nearby results as JSON or readable text.

Instructions

Return all places that match a category (industry, amenity, or NAICS‑style code). Use when the user asks for a type of place, plural or generic terms like 'museums', 'coffee shops', 'electric‑vehicle chargers', or when the query includes is‑a phrases such as 'any', 'all', 'nearby'. Do not use when a unique name or brand is provided. Supports both JSON and text output formats.

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": {
      "category": "<category>"
    },
    "name": "category_search_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
bboxNoBounding box to limit results within specified bounds
limitNoMaximum number of results to return (1-25)
formatNoOutput format: "json_string" returns raw GeoJSON data as a JSON string that can be parsed; "formatted_text" returns human-readable text with place names, addresses, and coordinates. Both return as text content but json_string contains parseable JSON data while formatted_text is for display.formatted_text
countryNoArray of ISO 3166 alpha 2 country codes to limit results
categoryYesThe canonical place category name to search for (e.g., "restaurant", "hotel", "cafe"). To get the full list of supported categories, use the category_list_tool.
languageNoIETF language tag for the response (e.g., "en", "es", "fr", "de", "ja")
proximityNoLocation to bias results towards as {longitude, latitude}. If not provided, defaults to IP-based location.
poi_category_exclusionsNoArray of POI categories to exclude from results

Output Schema

NameRequiredDescriptionDefault
typeYes
featuresYes
attributionYes
mapboxRenderNoMap-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 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"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / properties / features / items / properties / geometry / properties / coordinates / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / features / items / properties / geometry / properties / coordinates / maxItems
      Added value: +2
    • addedOutput schema / properties / features / items / properties / geometry / properties / coordinates / minItems
      Added value: +2
    • addedOutput schema / properties / features / items / properties / geometry / properties / coordinates / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedOutput schema / properties / features / items / properties / properties / properties / bbox / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / features / items / properties / properties / properties / bbox / maxItems
      Added value: +4
    • addedOutput schema / properties / features / items / properties / properties / properties / bbox / minItems
      Added value: +4
    • addedOutput schema / properties / features / items / properties / properties / properties / bbox / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • 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/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered; the description adds little beyond that. The mention that both output formats return as text content but json_string is parseable is mildly useful behavioral context, but ordering, truncation behavior, and whether a bare category search without proximity falls back to IP location are left unstated (the latter lives only in the schema).

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

Conciseness5/5

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

Three short sentences structured as purpose, when-to-use with examples, then the exclusion, followed by a brief format note. The core routing information is front-loaded and no sentence is filler.

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?

With rich annotations, 100% schema coverage, and an output schema handling returns, the description needs only to establish purpose and routing, which it does. A brief note on result ordering or how results relate to place_details_tool for follow-up lookups would make it fully self-sufficient.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter including bbox, limit, country, proximity, language and the format enum is already documented in structured data. The description's only added semantics is the category taxonomy and the pointer to category_list_tool, which itself appears in the schema, so this rests at the baseline 3.

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?

"Return all places that match a category (industry, amenity, or NAICS-style code)" gives a specific verb plus resource and even names the category taxonomy, which lets an agent separate it from a name/brand lookup or a geometry tool. It is immediately clear this is a plural/type-based place search, not a single-result lookup.

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?

The description gives concrete positive triggers ("museums", "coffee shops", "electric-vehicle chargers", is-a phrases like "any", "all", "nearby") and an explicit negative condition ("Do not use when a unique name or brand is provided"). It stops short of naming the sibling to use instead for brand/name queries, so the agent must infer the handoff.

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