MapsData

Start a scrape

mapsdata_start_scrape

Start scraping Google Maps businesses and their emails. Returns IMMEDIATELY with a job id; the scrape itself takes 5 minutes to several hours.

Before calling this, confirm the category with mapsdata_search_categories and the region with mapsdata_list_regions. Those two mistakes are the overwhelming majority of rejections.

This consumes the user's monthly lead allowance. Set dry_run to check a request against every rule without spending anything.

min_reviews, max_reviews and max_emails_per_company are optional. Pass them when the user asks for them. The response reports the filters that apply, including the default email cap.

Input Schema

Name	Required	Description	Default
`query`	Yes	An exact Google Maps category, e.g. 'Plumber'. Verify it with mapsdata_search_categories first.
`cities`	No	Named cities instead of whole regions.
`states`	No	Full region names, e.g. ['Texas']. Not abbreviations. Use this or cities, not both.
`country`	No		us
`dry_run`	No	Validate against every rule and return the plan WITHOUT starting a scrape or spending quota.
`list_name`	No	Label for the list. Defaults to the query.
`limit_basis`	No	What total_limit counts. 'emails' stops once that many leads WITH an email are found; leads without one are still delivered and never billed. 'rows' stops at that many leads of any kind. Omit it for the organization's default, which is 'emails' unless the organization used the API before this option launched.
`max_reviews`	No	Skip businesses with more Google reviews. Omit it for no maximum. 0 keeps ONLY businesses with no reviews.
`min_reviews`	No	Skip businesses with fewer Google reviews. Defaults to 0, no minimum.
`total_limit`	Yes	How many leads to scrape, in the unit limit_basis sets. Read max_rows_this_scrape from mapsdata_get_usage first: a larger request is reduced to the allowance left this cycle, not rejected.
`max_emails_per_company`	No	Most emails kept per business. Defaults to 5 when omitted.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 4, 2026

addedInput schema / properties / max_emails_per_company

Added value: +{
+  "description": "Most emails kept per business. Defaults to 5 when omitted.",
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / max_reviews

Added value: +{
+  "description": "Skip businesses with more Google reviews. Omit it for no maximum. 0 keeps ONLY businesses with no reviews.",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / min_reviews

Added value: +{
+  "description": "Skip businesses with fewer Google reviews. Defaults to 0, no minimum.",
+  "minimum": 0,
+  "type": "integer"
+}

Changed2 schema fields changedOct 29, 2026

addedInput schema / properties / limit_basis

Added value: +{
+  "description": "What total_limit counts. 'emails' stops once that many leads WITH an email are found; leads without one are still delivered and never billed. 'rows' stops at that many leads of any kind. Omit it for the organization's default, which is 'emails' unless the organization used the API before this option launched.",
+  "enum": [
+    "emails",
+    "rows"
+  ],
+  "type": "string"
+}

changedInput schema / properties / total_limit / description

Previous value: -"Rows to scrape. Read max_rows_this_scrape from mapsdata_get_usage first: a larger request is reduced to the allowance left this cycle, not rejected."New value: +"How many leads to scrape, in the unit limit_basis sets. Read max_rows_this_scrape from mapsdata_get_usage first: a larger request is reduced to the allowance left this cycle, not rejected."

First observedOct 15, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already mark this as non-read-only, open-world, non-idempotent, and non-destructive. The description adds crucial behavior beyond that: it returns immediately with a job id, the scrape may take minutes to hours, it consumes monthly lead allowance, dry_run avoids spending quota, and the response reports applied filters including the default email cap.

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?

Front-loads the core action and async return behavior, then moves through prerequisites, quota impact, dry_run, and optional filters in short, purposeful paragraphs. Every sentence contributes operational guidance with no wasted wording.

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 an 11-parameter asynchronous mutation tool with no output schema, the description covers the essential context: job id return, long runtime, quota consumption, validation prerequisites, dry_run safety, optional filters, and applied response filters. An agent has enough information to decide whether and how to call it correctly.

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 description coverage is high at 91%, so the schema already defines most parameters. The description still adds useful meaning by explaining that min_reviews, max_reviews, and max_emails_per_company are optional and should be passed when the user asks, and by noting that the response reports the filters that apply including the default email cap.

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?

Starts with a specific verb and resource: scraping Google Maps businesses and their emails. It also clarifies the asynchronous behavior by saying it returns immediately with a job id, which distinguishes it from sibling tools like mapsdata_get_scrape and mapsdata_cancel_scrape.

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?

Explicitly tells the agent to verify category via mapsdata_search_categories and region via mapsdata_list_regions before calling, naming the most common rejection causes. It also explains when to use dry_run and when to pass optional filters, which is exactly the guidance needed for correct invocation.

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

All MapsData tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?