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 cover the safety profile (readOnly, idempotent, non-destructive), so the description correctly spends its words on non-obvious behavior: the result is a point-in-time snapshot of a long-running job rather than a final answer, and the response carries a next_action directive. It stops short of describing polling etiquette beyond 'no loop' or whether repeated reads are cheap.

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, each load-bearing: what it does, what it returns in kind, and how to use it. The polling prohibition is prominent early rather than buried.

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, and the description compensates by naming the key response field (next_action) and the out-of-band completion signal (email). What remains unstated is the rest of the response shape and the idempotency cost of re-reading, but the calling agent has enough to invoke 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?

Only one parameter (job_id) with 0% schema description coverage, so the schema supplies no semantics. The description implies job_id identifies a particular scrape but never states the format or where the id comes from (presumably mapsdata_start_scrape). Adequate but incomplete for the only input the agent must supply.

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 bounds the scope to a single job, which separates it from the plural sibling mapsdata_list_scrapes. The added 'INSTANT SNAPSHOT of a job that runs for minutes to hours' tells the agent exactly what kind of object it is querying.

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 an explicit when-not ('Do NOT call it repeatedly in a loop') plus the correct alternative behavior instead of polling ('Read next_action in the response and follow it'). It also notes that email notification handles completion, so the agent knows polling is unnecessary — concrete routing guidance rather than implied usage.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the rejection rule for abbreviations and the reason (postal tables key on full name) — behaviourally useful context an agent cannot infer from 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.

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

Three short sentences, front-loaded with the action, then the usage rule, then the rationale. No filler and nothing repeated from the title.

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 enumeration tool with full annotation coverage and no output schema, the description tells an agent what it returns (region names), why they matter, and how to use them. Only the country parameter's value set and default are left implicit.

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 carries the burden. It conveys that region names are country-scoped, linking the regions to the 'country' parameter, but never explains the parameter's accepted values or its 'us' default — that is left entirely to the enum. Partial compensation only.

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 — list the exact region names a scrape accepts for a country — and adds the crucial qualifier 'accepts', which distinguishes it from generic region lookups and from siblings like list_scrapes or search_categories.

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 clear context for use (fetch the names before submitting a scrape) and the operational rule 'submit them verbatim'. No alternative tool is named, but none of the siblings offer an overlapping capability, so the omission is low-cost.

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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds the 'newest first' ordering behavior, which is genuinely useful context, but says nothing about pagination, truncation at the limit cap, or that it is workspace-scoped beyond the phrase itself.

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?

One sentence, zero filler, with scope and ordering front-loaded. Nothing to trim.

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 list tool with no output schema and two undocumented parameters, the description is too thin — no return-shape hint, no pagination or cursor behavior, no mention of the status filter. It leaves the agent to reverse-engineer usage from the schema alone.

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 carry the burden and it does not: neither the 'limit' cap (max 25) nor the 'status' enum filter (queued/running/cancelling/cancelled/completed/failed) is mentioned. An agent reading only the description would not know it can filter by scrape status.

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+resource and a scope ('this workspace's recent scrapes') plus an ordering guarantee ('newest first'). It does not, however, distinguish itself from siblings such as mapsdata_get_scrape (single scrape) or mapsdata_start_scrape, though the list-vs-get distinction is fairly intuitive.

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 is implied — an agent can infer this is the discovery/overview tool for prior scrapes — but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives like mapsdata_get_scrape for a specific scrape or mapsdata_start_scrape for a new one.

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 declare non-read-only, non-idempotent, open-world, non-destructive, but the description adds behavior they cannot convey: asynchronous job-id return, multi-minute-to-hour duration, and consumption of the user's monthly lead allowance. It explicitly documents the cost-avoidance path via dry_run, which is the key behavioral risk for this tool.

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 sentences, each earning its place: purpose/timing first, prerequisites second, cost warning third. No restatement of the title or filler, and the most decision-relevant facts (async, cost) are front-loaded.

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 7-param async job-starter with no output schema, the description covers the return shape (job id), the cost model, and the validation path. It does not state how to retrieve results afterward (e.g. mapsdata_get_scrape), which is discoverable from siblings but would close the loop fully.

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 already 86%, so the schema carries most parameter meaning (baseline 3). The description adds real value beyond it by explaining dry_run ('check a request against every rule without spending anything') and the quota consequence of total_limit, which the schema only states indirectly.

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+resource (scrape Google Maps businesses and their emails) and immediately characterizes the operating mode: 'Returns IMMEDIATELY with a job id; the scrape itself takes 5 minutes to several hours.' This is a concrete, distinguishable purpose relative to siblings like mapsdata_get_scrape or 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?

Gives explicit prerequisites ('confirm the category with mapsdata_search_categories and the region with mapsdata_list_regions') and names the sibling tools to call first, plus the rationale that these are the majority of rejections. It also names a when-to-use variant (dry_run) with its purpose. Nothing is left to inference.

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