MapsData

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

Annotations already flag destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds non-obvious billing semantics that no annotation conveys: queued cancels are free while cancelling a running scrape still charges for leads already delivered. It also translates the destructive flag into an actionable instruction (get user confirmation), which is exactly the value the description should add.

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?

Three short sentences, front-loaded with the operation, then cost behavior, then the confirmation requirement. The capitalization on the billing warning is a deliberate emphasis on the highest-risk fact, and no sentence is filler.

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 single-parameter destructive mutation, the description covers the risk profile and the user-confirmation protocol well. The only real omission is what the call returns or how to verify the cancellation succeeded (no output schema exists to fill that in), which is minor but leaves a small unknown.

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?

Schema description coverage is 0% and the single parameter job_id is undocumented in both schema and description. The phrase 'a queued or running scrape' weakly implies job_id identifies a scrape job, but the description never states the expected identifier form or where to obtain it, so it does not compensate for the coverage gap.

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?

States a specific verb (Cancel) and resource (a queued or running scrape), and the scope distinction ('queued OR running') is a real refinement rather than a restatement of the title. An agent can immediately separate this from siblings like mapsdata_start_scrape or mapsdata_get_scrape.

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?

Gives a clear condition for invocation (targeting a job that is queued or running) and an explicit prerequisite behavior: confirm with the user before calling. It does not name a sibling alternative, but there is no competing cancel-style tool in the sibling list, so the missing alternative reference is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, destructiveHint=false and idempotentHint=false, so safety is covered. The description adds genuinely new behavior: the link expires in 15 minutes and should not be persisted, which materially shapes how an agent should handle the result.

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?

Two short sentences, front-loaded with the purpose and followed immediately by the actionable expiry constraint. No filler.

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?

Purpose and the critical expiry behavior are covered, and there is no output schema to explain. However, for a 3-parameter tool with two enums and only 33% schema coverage, the description leaves format choices and the billing-relevant scope selection entirely to the schema, which is only partly documented.

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?

Schema description coverage is only 33% — only 'scope' is documented, while 'format' and 'job_id' carry no description. The description contributes no parameter meaning at all (no mention of scope, format, or what job_id refers to), so it fails to compensate for the coverage gap.

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?

States a specific verb ('Get a link') and resource ('a finished scrape's results'), which clearly separates it from siblings like get_scrape or list_scrapes. It does not name a sibling explicitly, but the link-vs-data distinction is inferable.

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?

The second clause gives real operational guidance ('hand it to the user promptly rather than storing it'), which is a when-to-do-something-afterward instruction. It says nothing about when to choose this tool over get_scrape or list_scrapes, so usage selection against alternatives is only implied.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the call is an instant snapshot of a job that runs minutes to hours, and the response carries a next_action field guiding the subsequent step.

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?

Four short sentences, front-loaded with the core purpose, then the polling caveat and return-value hint. No filler; each sentence adds an actionable fact.

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?

No output schema exists, and the description compensates by describing the key return field (next_action) and the out-of-band completion email. For a one-parameter read tool with full annotation coverage, this is close to complete, though it omits where job_id originates.

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?

Schema coverage is 0% and the description says nothing about the single parameter job_id — no format, origin, or where it comes from (presumably start_scrape or list_scrapes). The name is largely self-explanatory, but the description contributes no meaning beyond the schema.

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?

States a specific verb and resource ('Get the current state of one scrape'), and the singular scoping distinguishes it from the sibling mapsdata_list_scrapes and mapsdata_start_scrape. An agent can identify the target operation without opening any schema.

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?

Gives explicit negative guidance ('Do NOT call it repeatedly in a loop') and explains that MapsData emails the user on completion, which tells the agent when to stop polling. It stops short of naming the alternative sibling (e.g. list_scrapes) for enumerating multiple jobs, so the routing picture is not fully complete.

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

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

Annotations already establish this as a safe, idempotent, read-only operation, so the bar is lower. The description still adds behavior beyond them: the allowance is scoped to the current month and the per-scrape cap is a plan-level constraint. It omits the precise response shape, but for a no-parameter read this is substantive added context.

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?

Two short sentences, both front-loaded with the payoff. Every clause earns its place: the first defines the returned data, the second drives the correct downstream action.

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?

With no output schema and no parameters, the description must convey what comes back, and it does explain the two headline values. It leaves minor gaps such as plan identity or scrape counts that might also be in the response, but nothing an agent needs in order to call it correctly is missing.

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 tool takes zero parameters, so the baseline is 4 by rule. The mention of max_rows_this_scrape is a return field rather than an input, which is correctly framed as something to read rather than something to pass, so nothing is misleading.

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 the concrete resource and the exact data returned: remaining monthly lead allowance and the per-scrape row maximum. No sibling (cancel/get/list/search/start scrape) overlaps with plan-usage reporting, so the agent can identify it uniquely. It stops short of a crisp leading verb like "Get usage," which keeps it from a perfect 5.

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 gives explicit action-oriented guidance: read max_rows_this_scrape before choosing a total_limit. That tells the agent to call this as a pre-flight check before mapsdata_start_scrape, which is real when-to-use context. It does not name the sibling tools directly, so it falls just short of full routing guidance.

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

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 a real behavioral constraint — that abbreviations like 'TX' are rejected and names must be submitted verbatim — which is useful context beyond the annotations. It does not describe the response shape or any rate/limit behavior.

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?

Three short sentences, front-loaded with the core purpose and followed by the critical usage constraint. Every sentence earns its place with no filler.

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 simple read-only list tool with one enum parameter, annotations covering safety, and no output schema, the description is nearly complete — it says what is listed and the strict verbatim requirement. It could have named the supported country values to fully compensate for the 0% schema coverage, which is the only notable gap.

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?

Schema description coverage is 0%, so the description must compensate. It mentions 'for a country', mapping loosely to the single parameter, but never explains the allowed enum values (au, ca, uk, us) or the default of 'us'. The enum in the schema carries the real meaning, leaving a clear gap the description should have filled.

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 exact region names a scrape accepts for a country'), which is far more concrete than the title alone. It does not explicitly contrast with siblings like mapsdata_search_categories or mapsdata_list_scrapes, but the scope is unambiguous enough that an agent can distinguish it.

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?

Usage guidance is limited to how to consume the results ('Submit them verbatim', abbreviations rejected). There is no explicit when-to-use or when-not-to-use guidance, nor mention of the natural pairing with mapsdata_start_scrape. Implied usage only.

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

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

The annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by specifying organization scope and newest-first ordering, but it does not describe return format, pagination behavior, or how filtering affects results.

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 a single front-loaded sentence with no filler. Its scope and ordering information appear immediately.

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 tool has two optional parameters with no schema descriptions and no output schema, yet the description does not explain parameter behavior or return values. Annotations cover the safety profile, but the definition remains too sparse for an agent to understand filtering and result shape without inference.

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?

Schema description coverage is 0%, and the description does not mention either parameter. It says nothing about the `limit` cap/default or the `status` enum, so an agent must rely entirely on the bare schema.

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 clear verb and resource: "List this organization's recent scrapes." It also adds scope and ordering with "this organization's" and "newest first." It does not explicitly distinguish itself from the sibling `mapsdata_get_scrape`, so it is clear but lacks sibling differentiation.

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?

The description says what the tool does but gives no guidance on when to use it instead of alternatives such as `mapsdata_get_scrape` or `mapsdata_start_scrape`. There are no stated preconditions, exclusions, or usage context.

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

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

Annotations already establish that this is a safe, idempotent, non-destructive, non-open-world read. The description adds meaningful domain behavior beyond that: this tool exposes the exact controlled vocabulary required by mapsdata_start_scrape, and free-text queries are rejected. It does not cover rate limits or auth, but the core behavioral constraint is disclosed.

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?

Two tightly written sentences with no waste. The critical instruction to call this first and the reason for it are front-loaded, so an agent can act immediately.

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?

There is no output schema, but the description still makes clear that the tool returns the allowed category vocabulary and why that matters for scraping. It does not describe the exact response shape, but for a simple lookup with strong annotations, the description is nearly sufficient.

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?

Schema coverage is 50%; the query parameter is described as a substring search and the limit parameter has self-evident constraints (min 1, max 50, default 10). The description does not add parameter-level syntax or format details beyond the schema, though it does clarify the conceptual role of the category results.

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: search the Google Maps business categories that MapsData can scrape. It is immediately distinguishable from siblings like mapsdata_start_scrape because it is the category-vocabulary lookup, not the scrape itself.

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 gives an explicit ordering instruction: call this first, before mapsdata_start_scrape. It also explains the selection condition and consequence: a scrape's query must be one of these exact categories, and free-text guesses are rejected.

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

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.

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.

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.

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.

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.

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.