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

Beyond the basic readOnly and destructive hints in annotations, the description adds vital behavioral context: the cost (81 credits per domain), the guaranteed scope (country-level), and the specific metrics returned. This significantly reduces ambiguity.

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 definition is highly efficient. It front-loads the core function, immediately provides the necessary operational constraints (cost/metrics), and ends with clear decision trees (when to use this vs. when to use siblings).

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 addresses all likely cognitive blockers for the agent: output metrics, cost, hard operational constraints (2-5 domains), and scope limitations (country-level). It is perfectly suited for its complexity.

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?

Since schema coverage is 100%, the description does not need to explain data types. However, it enhances semantics by adding critical structural constraints that the schema handles passively, such as the 2-5 domain limit and the definitive country-level scope of the location parameter.

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 clearly defines the function (compares 2-5 domains' AI visibility) and the exact output metrics (total_mentions, total_impressions, ai_search_volume). It also provides immediate differentiation by referring the user to ai_visibility for a detailed platform breakdown.

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 provides extensive usage guidance by defining clear boundaries: 1) for detailed breakdowns, use ai_visibility; 2) for city-level results, use ai_scraper or ai_mode. Crucially, it establishes that the tool operates strictly at a country level, despite location input.

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?

Goes well beyond the readOnly/openWorld annotations by disclosing the country-level volume scope caveat, the instruction to check location_used, and a credit cost model (9-16 credits, scaling with keyword count, 100 keywords = 16). That cost and scope information is exactly the kind of behavioral detail an agent needs before calling.

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, each carrying distinct information (use case, return fields, scope caveat, cost). The use case is front-loaded and the 'IMPORTANT' marker correctly flags the one gotcha an agent could trip on.

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 an output schema present, return values don't need explanation, and the description nonetheless names the key fields. Cost, scope limitation, and default behavior are all covered, leaving nothing an agent needs in order 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?

Schema coverage is 100%, yet the description still adds real meaning: it warns that results are country-level regardless of the location argument and points at location_used for verification, and it ties keyword count to credit cost. This is substantive guidance beyond the field 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?

States a specific verb and resource — measuring how often keywords are searched in ChatGPT and other LLMs — and names the return fields (ai_search_volume, monthly trend). The 'AI' qualifier implicitly separates it from the Google-oriented search_volume sibling, so an agent can pick it without opening the 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?

'Use when measuring how often keywords are searched in ChatGPT and other LLMs' gives a clear triggering condition. It stops short of explicitly routing the agent away from search_volume or keyword_trends for traditional search data, so the alternative 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?

Goes well beyond the readOnly/openWorld annotations: exact credit costs including premium/frontier model pinning and search-priced tiers, 15-60s latency, one-hour caching with the fresh escape hatch, per-platform 400 failures, and the Gemini registrable-domain collapse that changes how citations must be matched. The sampling-variance warning ('treat one run as a sample') is precisely the kind of non-obvious behavior an agent cannot infer from structure.

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-loaded with purpose and output shape, then clearly demarcated by capitalized headers (COST, ACCURACY WARNING, MATCHING CITATIONS), so an agent can skim to the section it needs. It is long, and a few facts (web_search pricing, force_web_search platform limits) repeat what the schema already states, which is wasted weight rather than harmful.

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?

An output schema exists, so return values need no prose, and the description still supplies everything else an agent needs to call correctly: which platforms compel vs permit search, cost tradeoffs, latency expectation, nondeterminism, and the citation-matching caveat. Nothing material is left for the caller to discover by trial and error.

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 100%, so the baseline is 3; the description earns above that by stating the platform-by-platform support matrix as a coherent rule (claude gets the full set, GPT-5 drops force_web_search, gemini is web_search-only and un-geocodable, perplexity is search_country-only) and the dependency that force_web_search requires web_search: true. Some of this duplicates the per-parameter schema text, keeping it out of the 5 band.

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?

Opens with a specific verb+resource ('Gets what a specific LLM says about a query') and immediately enumerates the return payload and supported platforms, so the agent knows exactly what the tool does and which models it can address. It is distinguishable from the surrounding ai_* siblings by being the raw per-platform query tool rather than an aggregate/visibility metric.

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 conditional guidance: perplexity always searches and needs no parameters, the other three need web_search: true for local business questions, and the accuracy warning directs the agent to a searching platform when checking a real business. It stops short of naming sibling tools (ai_overview, ai_mode, ai_sample) as alternatives, so the routing against the rest of the family is left implicit.

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 read-only/open-world, and the description adds substantial context beyond them: credit cost (5 with lookup, 1 without), a confidence scale with thresholds, the exact match precedence chain, false-signal rules (shared hosts, name containment, address agreement), and what entity_variants and nap_conflicts actually mean. This is behavioral disclosure that annotations cannot carry.

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-loaded with "Use when..." and organized under clear headings, with no sentence that is pure padding. It is long and the capitalized emphasis headings add bulk, but for a tool with this much matching nuance the length is largely earned rather than 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?

Despite an output schema existing, the description still explains how to read confidence, matched, identifier_coverage, entity_variants and nap_conflicts — the fields most likely to be misreported. Nothing an agent needs to call this correctly or interpret results 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?

Schema coverage is 100%, so baseline is 3; the description still adds real meaning by explaining the interaction between place_id and location, that cid belongs inside target and skips the lookup, the resolve default logic, and that extra fields in passed arrays are ignored. It slightly restates schema-documented identifiers (domain/website/phone all "skip the lookup"), which keeps it from a perfect score.

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 first sentence states a specific verb and resource — deciding whether a business an AI named is the business being tracked — and names the sibling tools (ai_scraper, ai_mode, ai_sample) that produce its input. An agent can distinguish it from the surrounding AI-visibility tools without opening the 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?

It explicitly states the two entry modes and their exclusivity ("Pass one or the other, never both"), when a lookup occurs versus not (cid/domain/phone supplied), when to filter on matched_on, and the edge case that a low rate should be reported alongside identifier_coverage. Alternatives and exclusions are named rather than 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/openWorld/non-destructive, so safety is covered; the description goes further with behavior the annotations cannot express — results are country-level regardless of the location passed, the returned location_used should be verified, and each call costs 88 credits. That is exactly the kind of hidden trait an agent needs before calling.

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?

Tight and front-loaded: purpose, then return shape, then the IMPORTANT caveat, then the alternative, then cost. The mid-sentence enumeration of return fields (question, answer_snippet, sources_cited, platform) is partly redundant given an output schema exists, but it is compact enough to earn its place.

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 5-parameter, read-only, open-world tool with a full output schema and full annotation coverage, nothing an agent needs is missing: purpose, scope degradation caveat, alternative routing, and cost are all stated. Output schema handles return values, so the description need not expand further.

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 100%, so the baseline is 3. The description adds real semantics beyond the schema: it warns that the 'location' parameter is silently degraded to country scope even for a city input, which directly contradicts what the schema example ('Portland, OR') implies. Other parameters are left to the schema, which is adequate.

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 first sentence gives a specific verb ('finding where a keyword appears') and a specific resource scope ('ChatGPT and Google AI outputs'), and the return fields (ai_search_volume, total_mentions, mention details) pin down the output shape. An agent can distinguish this from ai_visibility or brand_mentions without opening the 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?

Explicitly states the condition for use ('finding where a keyword appears') and names the alternatives with their own condition: 'For city-level AI results use ai_scraper or ai_mode.' It also flags the 88-credit cost, which lets an agent make a cost/benefit call before invoking.

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?

Goes well beyond the readOnly/openWorld/destructive annotations: discloses the 2-credit cost, the 10-30 second latency and why (Google generates per request), that results are cached for an hour, the meaning of each parse_status value, that reviews_count is rounded, and that references is unreliable. These are exactly the non-obvious traits an agent needs to interpret 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?

Front-loaded with purpose, cost, and latency, which is good. However, most of the remaining length enumerates return-field semantics and caveats, and since an output schema exists some of this is redundant; the dense field-by-field commentary is not as tight as it could be.

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 tool with an output schema, two required params, and cost/latency involved, the description covers everything an agent needs to call it correctly and to avoid misreading results (rounding, empty cid, unreliable references, parse_status failures).

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 100% and the fresh parameter is already fully explained including the billing caveat in the schema. The description adds invocation-level cost/latency context but no per-parameter syntax or semantics beyond what the schema provides, 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?

States a specific verb and resource ('getting the Google AI Mode (SGE) generated answer for a keyword') and then names what comes back. It also distinguishes itself from siblings by explicitly contrasting field sets with /v1/serp/local-pack and calling out two differences from ai_scraper on chat_gpt (phone always empty, cid populated).

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?

'Use when getting the Google AI Mode (SGE) generated answer for a keyword' is an explicit trigger condition, and the fresh parameter guidance tells the caller when bypassing cache matters. There is no explicit 'when not to use' or routing to ai_overview/ai_scraper, so it stops short of 5.

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?

Goes well beyond the readOnlyHint/openWorldHint/destructiveHint annotations: 2-credit cost, 10-30 second latency, the reason for that latency (a second request to Google for asynchronous overviews), and the guarantee that summary_text and cited_sources are populated in both sync and async cases. The position numbering rule and duplicate-collapse behavior are also 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?

Front-loaded with the use case, then return fields, then behavioral caveats (async, cost, latency). Every sentence contributes a distinct fact and there is no repetition of the schema.

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?

Covers the things an agent cannot get from structured fields: cost, runtime, caching, and the async-overview edge case. Although an output schema exists (so return documentation is somewhat redundant), the explanation of asynchronous_ai_overview and citation position ordering adds real interpretive value for a 3-parameter, single-purpose tool.

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 100%, including a thorough explanation of the non-obvious 'fresh' cache-bypass flag, so the schema already carries parameter meaning. The description adds nothing further about keyword/location/fresh semantics and instead spends its words on return shape. Baseline 3 is appropriate.

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: checking whether Google shows an AI Overview for a keyword and which sources it cites. That is unambiguous and distinct in meaning from generic SERP tools. It never names or contrasts itself with close siblings like ai_mode, ai_visibility, or ai_mentions, so the agent must infer the boundary.

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?

'Use when checking if Google shows an AI Overview for a keyword' gives a clear triggering condition. There are no explicit exclusions or alternatives — nothing tells the agent when to pick ai_mode or ai_visibility instead of this tool, which matters given the dense AI-* sibling cluster.

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 read-only and open-world, and the description still adds substantial operational context beyond them: the call is asynchronous, returns a job_id immediately, costs 1-3 minutes, typical completion is 30-60s with a 130s worst case, deduplication replays identical requests within 10 minutes at 0 credits, and incomplete samples are refunded with credits_charged as the final figure. That is exactly the behavioral payload annotations cannot express.

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 lead sentence front-loads the decision criterion, and the labeled sections (COLLECTING, WHY SAMPLE, REPEATS, PLATFORMS, COST) make it scannable. It runs long for a tool description and repeats the dedup window in both REPEATS and the force_new schema text, so a sentence or two could be trimmed.

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 asynchronous, credit-consuming tool with an output schema, the description supplies everything an agent needs to call it and act on it: the polling cadence against ai_sample_status, cost math before spending credits, refund behavior, and dedup semantics for safe retries. Nothing material is left to 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter economics (samples x per-run price, 4 credits on chat_gpt vs 2 on google_ai_mode, location required for google_ai_mode) and the reasoning behind force_new and idempotency_key rather than restating their schema text. The extra value is real but partly duplicative of the schema wording.

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?

Opens with a specific use condition — measuring HOW OFTEN an AI answer names a business, explicitly contrasted with a single-answer tool — and names both the resource sampled and the job-based return shape. It also distinguishes itself from siblings (ai_scraper, ai_mode, mention/visibility tools) so the agent can route correctly without opening a 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?

The 'WHY SAMPLE' section states exactly when this tool is right (a client asking for a rate) and when it is not (mention and visibility tools read stored aggregates, so running them repeatedly returns identical numbers). It also names the follow-up tool (ai_sample_status) and the overrides (force_new, idempotency_key) with the condition that selects each.

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 safety (readOnly, non-destructive, openWorld), and the description layers on non-obvious behavior: this poll costs 0 credits, credits_charged is the submit reservation minus refunds, refusals are not refunded, and failed jobs are refunded in full. It also discloses the returned statuses and their shapes, which no annotation conveys.

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?

Status semantics and the free-to-poll point are front-loaded, and section headers (WHAT COMES BACK, TWO DIFFERENT RANKINGS, GEMINI, READING THE RATES, BILLING) aid scanning. It is nonetheless very long for a single-parameter poll, and the name-merging discussion is a dense paragraph that could be tightened.

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 the complexity of the payload — listing vs. shortlist rankings, gemini's missing listing, rates out of samples_returned, matched_on strength, name merging — the description supplies the interpretive guidance an output schema cannot. Nothing needed to read the result 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?

Only one parameter and schema coverage is 100%, with the schema itself saying 'The job_id ai_sample returned.' The description adds no syntax or format detail beyond that, so the schema is doing all the work — baseline 3 for a fully covered 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 — 'Collects the answer to an ai_sample job' — and explicitly ties it to the sibling that creates the job. An agent can tell this is the status/result-fetch counterpart to ai_sample 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?

'FREE — poll as often as you need' plus the pending/running/complete/failed breakdown makes the polling usage pattern clear, and typical timing (30-60s, tail ~130) implies cadence. It stops short of naming alternatives (e.g. ai_llm_response or ai_visibility) or stating when NOT to call it, so no exclusions.

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?

Adds substantial context the annotations cannot carry: 4-credit cost, 30-90 second live latency with an explicit 'do not retry' warning, hour-long caching, and Gemini's 400 on force_web_search. It also discloses that search_results is unpopulated and that fan_out_queries/brand_entities are often empty.

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 trigger well, but the body sprawls across six all-caps sections and spends a lot of prose on return-value semantics that an output schema already covers. The two-rankings warning earns its place; the LOCAL BUSINESSES field-by-field recap is redundant padding.

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?

Despite an output schema, the description supplies the interpretive knowledge an agent cannot derive structurally: local_businesses vs recommended_businesses ordering divergence, listed/shortlist_rank null semantics, and Gemini's empty-listing trap. Nothing needed 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?

Schema coverage is 100%, so every parameter is already documented in the schema, and the description largely restates force_web_search behavior rather than extending it. No new syntax, format, or edge-case detail is added for keyword, location, language or fresh.

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?

Opens with a specific trigger verb and resource: scrape ChatGPT or Gemini search results for a keyword. The distinction from siblings like ai_mode or ai_llm_response is only implicit (platform-level AI answers), never named, so it misses the top band.

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 when-to-use context ('Use when scraping ChatGPT or Gemini search results for a keyword') plus situational guidance for force_web_search and for reading recommended_businesses on Gemini. It never names a sibling alternative or an explicit when-not, so it stops short of 5.

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?

Beyond the read-only annotations, the description discloses critical behavior: results are country-level regardless of the location passed, city inputs resolve to country scope, location_used should be checked, and the call costs 81 credits. These are exactly the operational details an agent needs before invoking it.

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 front-loaded: purpose first, return fields second, the country-level caveat third, alternatives fourth, and cost last. Every sentence contributes actionable 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?

For a read-only, open-world lookup tool with full schema descriptions and an output schema, the description covers the remaining decision-critical context: granularity, country-level behavior, alternatives, and cost. Nothing important for correct invocation appears 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?

Schema coverage is 100%, so the baseline is 3, but the description adds important meaning about location semantics that the schema does not capture: location is effectively country-level and city values are resolved upward. It does not add much beyond the schema for limit, language, or platforms, but the location caveat is significant.

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 resource and scope: finding specific pages that AI models reference most, not just domains. It explicitly distinguishes the tool from ai_top_sources as more granular, so an agent can select it without opening either 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?

It gives an explicit use case and names alternatives for the key edge case: city-level AI results should use ai_scraper or ai_mode. It also makes clear that this tool is the page-level counterpart to ai_top_sources.

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?

Beyond the read-only and open-world annotations, the description discloses that results are country-level regardless of the city passed, that location_used should be checked, and that the call costs 81 credits. These are meaningful behavioral constraints and operational details not present in the annotations or 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?

The description is compact and front-loaded: purpose first, then return shape, sibling distinction, critical location caveat, alternatives, and cost. Every sentence carries useful information 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?

The tool has an output schema, so return values need not be fully explained. The description still covers the key caveat, alternatives for different granularity, and credit cost, making it complete enough for an agent to select and invoke 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?

Schema coverage is 100%, so the schema already documents all five parameters. The description adds critical meaning beyond the schema by explaining that location resolves to country level regardless of the provided city, which directly affects how the location parameter should be interpreted.

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: it discovers which domains AI models cite most for a topic. It also states the returned fields and explicitly distinguishes itself from ai_top_pages, which reports individual pages rather than domains.

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 directs agents to ai_top_pages for page-level results and to ai_scraper or ai_mode for city-level AI results. The country-level limitation is clearly stated, including the instruction to check location_used, which prevents incorrect 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?

Adds real behavioral context beyond the readOnly/openWorld annotations: a concrete cost (81 credits), the country-level resolution behavior that will silently differ from the requested city, and the instruction to verify location_used. It stops short of describing rate limits or failure modes, so not a 5.

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 purpose, then scope caveat, then alternatives, then cost. Every sentence carries distinct routing or behavioral information; nothing is padding, even though the field list partially duplicates the output schema.

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?

An output schema exists, so the return-value enumeration is mild redundancy rather than a gap. The description covers the two things an agent can't infer from structured fields: the credit cost and the country-level scoping gotcha. Minor omission: no hint about latency or how keywords affect volume of work.

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 100%, so baseline is 3. The description earns above baseline by correcting a misleading schema hint — 'location' is documented in the schema as accepting "Austin, TX"-style input, but the description warns the result is country-level regardless, which materially changes how an agent should use that parameter.

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 — measures a single domain's AI citation score across platforms — and immediately names the sibling it is not (ai_compare handles multiple domains side by side). An agent can distinguish it from ai_compare, ai_mentions, and ai_scraper 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?

Explicitly routes three ways: single domain here, ai_compare for side-by-side comparison, and ai_scraper or ai_mode for city-level AI results. The country-level scope caveat also tells the agent when this tool will NOT give what it wants.

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?

Goes well beyond the readOnly/openWorld annotations: discloses per-call cost (5 credits, 3 with muid) and the exact optimization path to reduce it. It pre-empts three common misreads of the response (matched:false, claimed:false vs claimed:null, data_source non-empty meaning Apple ingested from a provider), which are precisely the traps that would cause an agent to misreport 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?

Purpose is front-loaded in the first clause, then each subsequent sentence handles one distinct concern (existence states, claim states, data_source caveat, cost/optimization). Dense for its length but no sentence is filler, and the gotchas are ordered by likelihood of misinterpretation.

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?

An output schema exists so return shape is covered elsewhere, yet the description still explains how to interpret the ambiguous result fields, plus the billing model and cost tradeoff. An agent has everything needed to call it, interpret the response, and report findings without guessing.

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 100%, so the baseline is 3, but the description adds real value: it explains that platform_id from a response is the MUID to pass back as `muid`, and that doing so skips the name-resolution search. The 5→3 credit framing also clarifies muid's practical value, not just its type.

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?

Opens with a specific verb+resource+payload: fetches a business's Apple Maps listing, with the returned fields enumerated (NAP, rating, categories, coordinates). Distinguishes it from the generic business_profile / apple_maps siblings by naming the Apple Business Connect context explicitly.

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?

"Use when auditing Apple Business Connect or checking NAP consistency on Apple" gives a clear triggering condition and the tool's domain. It does not name alternatives (e.g., bing_business_profile for the Bing equivalent, or apple_maps for raw search results), so cross-tool routing is left partly to inference.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely valuable operational context (3 credits cost, 502 retry policy, claimed-state semantics, rating normalization, data_source caveats), but much of that is really about interpreting return values rather than how the tool behaves as a call. Solid but not exceptional behavioral disclosure.

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?

Purpose and trigger are front-loaded and every section is information-dense, but the single dense paragraph runs long and some field-by-field detail could be trimmed. Efficient rather than tight.

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?

An output schema exists, yet the description still anticipates the tricky interpretation cases an agent will hit: claimed:false vs claimed:null, provider-ingested records vs owner data, mixed rating scales, and the location-scoped 502. Given the tool's interpretive complexity, the coverage is complete.

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 100% with four documented parameters, so the schema does the heavy lifting. The description mentions location behavior only indirectly, via the warning not to substitute a nearby city, and says nothing about sort or limit; the baseline 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?

States a specific verb and resource: 'Checks how businesses rank on Apple Maps for a keyword.' It explicitly contrasts with the Google-oriented sibling local_pack, so an agent can distinguish it from maps, local_pack, and bing_local without opening a 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 trigger conditions (Apple Maps, Siri, Apple Business Connect, iPhone visibility) and names the alternative that does not cover them (Google local_pack). It also supplies operational guidance for the 502 partial-location failure, including retry once and never substituting a nearby city.

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, and destructiveHint, so the safety profile is covered. The description adds genuinely non-redundant behavior: the credit cost (23 credits) and the shape of what comes back, which an agent needs for cost-aware planning. No contradiction with 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?

Three short sentences: the trigger first, the return second, the cost last. Every sentence carries distinct information — no restatement of the title or the schema.

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?

An output schema exists, so return values needn't be spelled out, and all three parameters are documented inline. The description covers trigger, output gist, and cost; it does not mention the limit cap or result volume, which a 3-parameter costed tool could afford to note.

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 100%, with inline descriptions for limit (default 50, max 100), your_domain, and competitor_domains (1–5 items), so the baseline is 3. The description adds no parameter-level detail beyond naming competitors as the comparison target, so it neither compensates nor detracts.

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 — finds sites linking to competitors but not to the user's domain — and previews the return shape (referring domains with authority and competitor linkage). That distinguishes it conceptually from backlink_summary and competitor_gap, though neither sibling is named.

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?

"Use when finding link building opportunities" gives an explicit use context rather than leaving it implied. There are no stated exclusions or named alternatives (e.g., when to prefer competitor_gap or backlink_summary instead), so it stops short of a 5.

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 read-only, non-destructive, open-world operation. The description adds useful behavioral context by disclosing a 23-credit cost and summarizing the returned profile fields. It does not discuss rate limits or authorization, but the cost disclosure is a meaningful addition beyond the 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 three compact sentences, with usage context front-loaded, followed by return fields and cost. Every sentence carries actionable information and there is 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?

The tool has a simple one-parameter schema, an output schema, and annotations covering safety behavior. The description supplies the remaining relevant context: when to use it, what it returns, and its credit cost. Nothing material for invoking the tool 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?

There is one parameter and schema description coverage is 100%, so the schema fully documents the 'domain' argument. The description implies a domain input but adds no format, validation, or domain-handling detail beyond the schema. A baseline score of 3 is appropriate.

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 action and resource: getting a domain's backlink profile overview. It lists the returned metrics, making the tool's purpose concrete. It does not explicitly distinguish this overview from the sibling backlink_gap tool, so it misses full 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 opening phrase 'Use when getting a domain's backlink profile overview' gives a clear use condition. However, it does not name exclusions or compare against alternatives such as backlink_gap, so the agent must infer when this overview is preferable.

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 read-only and non-destructive semantics, and the description adds genuinely new context: the meaning of matched:false and its implication that Bing Places was never claimed, plus a concrete cost of 3 credits. It doesn't mention failure modes such as invalid location strings or quota exhaustion, so not a 5.

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 tight sentences, front-loaded with the verb and returned data, then usage, then the edge-case semantics and cost. Nothing is redundant or padded.

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?

An output schema exists, so return shape need not be explained, and the description still covers cost and the not-found case. The remaining gap is disambiguation from adjacent tools such as bing_local and business_profile, which the agent must resolve on its own.

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 100% with only two required params, and both are already documented in the schema. The description adds no syntax or format guidance for business_name or location beyond what the schema says, so the baseline 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?

States a specific verb and resource — fetching a business's Bing Maps listing — and names the returned fields (NAP, rating, coordinates), so the agent knows exactly what it gets back. It does not explicitly distinguish itself from near-siblings like bing_local or business_profile, which keeps it from a 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?

"Use when auditing Bing Places or checking NAP consistency on Bing" gives a clear triggering context. It stops short of naming an alternative for the same job (e.g., business_profile or apple_business_profile for other platforms), so routing between siblings still requires inference.

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?

Beyond the readOnly/openWorld annotations, it discloses the returned field set, explains the counterintuitive null rating, reviews_count=0, and claimed=null as platform limitations rather than data gaps, and states the cost (3 credits). This is exactly the context annotations cannot carry.

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 purpose is front-loaded in the first sentence, and every following sentence carries actionable payload — proxy rationale, return fields, null-field caveats, cost. No filler or restatement of the name.

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 an output schema present, the description need not enumerate return values, yet it pre-empts the most likely agent confusion (null rating, reviews_count=0, claimed=null). Combined with annotations covering safety and cost noted explicitly, nothing needed 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?

Schema description coverage is 100% and every parameter (keyword, location, limit) is documented in the schema itself. The description adds no parameter-specific syntax or constraints, so the baseline 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 ('Checks how businesses rank') and a specific resource ('Bing's local results for a keyword'), and the Bing framing cleanly distinguishes it from siblings like apple_maps, local_pack, and organic_serp. An agent knows exactly what this tool produces without opening the 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?

It gives concrete usage conditions — Bing, Bing Places, Copilot, or ChatGPT local recommendations — and explains the proxy rationale. It stops short of naming a specific alternative (e.g. the Google equivalent) or an explicit when-not-to-use case, so it is clear context without full routing.

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 read-only and open-world access, so the description's main contribution is the 23-credit cost, a genuinely useful operational detail absent from structured fields. Return contents are summarized but largely duplicated by the output schema, and nothing is said about pagination or coverage limits for the search.

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 tight sentences: trigger first, output shape second, cost last. Nothing is padded and the most actionable line is 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 two-parameter read-only tool with an output schema and full annotations, the description covers purpose, outputs, and cost adequately. The remaining gap is sibling disambiguation against ai_mentions, which matters in a toolset this dense.

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 100%, fully documenting business_name and the limit range/default. The description adds no parameter meaning beyond that, so the baseline 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?

States a specific verb and resource ('monitoring where a brand is mentioned online') plus the differentiating capability of sentiment analysis. It does not distinguish itself from the sibling ai_mentions, so an agent must infer which mention-tracking tool applies.

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?

'Use when monitoring where a brand is mentioned online' gives an implied context for use, but there are no exclusions, prerequisites, or named alternatives (notably ai_mentions or reputation_audit).

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, openWorldHint=true and destructiveHint=false, and the description adds real value beyond that: the credit cost model ('10 credits per 50 results'), the radius semantics, and the location_used echo. Minor deduction for referencing search_radius_km and location_used, which are not present in the input schema, which could make an agent search for a parameter it cannot set.

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?

A single front-loaded sentence opening with the usage trigger, followed by return fields, scoping behaviour and pricing. Every clause adds information an agent needs; nothing is redundant 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?

Pricing, radius scoping and result-set composition make this callable without follow-up questions, and an output schema exists so return values need not be enumerated. However the description enumerates return fields that the output schema already covers, and the phantom radius/location_used references slightly muddy the parameter picture.

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 100%, so both required parameters are already documented, establishing a baseline of 3. The description adds meaning about radius behaviour and an echoed location field outside the schema, but says nothing about the limit parameter or how it interacts with the per-50-results cost, so it does not materially enrich parameter semantics.

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 ('discovering all businesses in a category and location') and immediately scopes it against the wrong interpretation ('bulk discovery, not single business lookup'). An agent can distinguish this from a single-business lookup or profile tool without opening the 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 an explicit trigger ('Use when discovering all businesses in a category and location') plus one negative case (not single business lookup). It stops short of naming a specific sibling alternative such as local_finder or maps for overlapping discovery needs, so routing between near-duplicates is left partly to inference.

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 read-only and open-world behavior, and the description adds real operational context the annotations cannot: a 5-credit cost and a defined no-match path (matched=false plus up to 5 Maps suggestions with place_id for retry). It doesn't mention rate limits or auth, but it adds substantive behavior beyond structured fields.

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 tight sentences, front-loaded with the use case and followed by payload, fallback, and cost. Every sentence carries information an agent would otherwise have to guess.

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?

Covers the use case, the fallback behavior, and the credit cost; an output schema exists so the field list is supplementary. Only gap is that the field enumeration duplicates the output schema, but nothing an agent needs for correct invocation 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?

Schema coverage is 100%, so business_name, location and place_id are already documented. The description's 'place_id for exact retry' reinforces but does not meaningfully extend the schema's own 'Google Place ID for exact match', so baseline 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?

States a specific verb and scope: 'pulling one business's complete GBP data', plus an explicit field inventory. 'GBP' plus the Google Maps fallback makes it distinguishable from the apple_business_profile and bing_business_profile siblings without opening a 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?

'Use when pulling one business's complete GBP data' gives a clear selection condition, and the single-business scope implies it is not the tool for multi-record listing work. It does not name an alternative or exclusion explicitly (e.g. business_listings for bulk), so it stops short of a 5.

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?

With readOnly/openWorld annotations already covering the safety profile, the description adds substantial extra context: per-directory credit cost (2.5, 50 credits for the default 20, 125 for all 50), the fact that every selected directory is scanned whether or not a listing exists, and the exact meaning of null vs false match values. This goes well beyond the 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?

Front-loaded with the use case, then return semantics, then cost. Dense but every sentence carries actionable content; the only mild redundancy is restating return-value semantics that the output schema already covers.

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?

An output schema exists, yet the description still resolves the key ambiguities an agent would hit: what consistency_score means, how nulls differ from falses, and why directories_checked always matches the request. Cost and confirmation requirements are also covered, so nothing material 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?

Schema coverage is 100%, so baseline is 3. The description still adds meaning the schema does not: the credit math tied to `directories`, that a count takes the top N of 50, the default of 20, and the total cost ceiling. It doesn't add format hints for business_name/address/phone, which limits it to a 4.

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: checking NAP (Name, Address, Phone) consistency across named business directories (Yelp, BBB, Facebook, etc.). This clearly separates it from siblings like business_listings, local_audit, or profile_health, which do not audit citation consistency.

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?

Begins with an explicit 'Use when checking NAP consistency...' trigger and adds a strong gating condition: 'Expensive -- confirm with user first.' It does not name an alternative sibling tool or state when NOT to use it, which keeps it short of a 5.

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?

With readOnly/openWorld annotations already covering the safety profile, the description still adds real value: the 2-credit cost, the explicit data gaps (no headline/body text, landing URLs, or platforms), and the distinction between total_ads and total_available. Cost and coverage limits are exactly the kind of context annotations cannot 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?

Front-loaded with the trigger, then returns, then limitations and cost, with no filler sentences. The per-creative field enumeration is somewhat verbose given an output schema exists, but it is not wasteful enough to penalize heavily.

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?

An output schema covers return values and annotations cover safety, so the description only needs to add cost and data-coverage caveats — both are present, including what the source fundamentally lacks. Nothing an agent needs to decide or call 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?

Schema coverage is 100%, so domain/limit/format/location are already documented in the schema, and the description only implies limit behavior via 'total_ads (after limit)'. It adds no format or location filter semantics beyond the enum already present.

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: what Google Ads a competitor domain is running. Clearly distinct from organic SERP or keyword siblings, though it doesn't explicitly separate itself from the local_services_ads sibling, which is the nearest neighbor an agent could confuse it with.

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?

'Use when seeing what Google Ads a competitor domain is running' gives a clear triggering context. No explicit when-not conditions or named alternatives, so it stops 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?

The description adds important behavior beyond the annotations: it discloses credit costs, per-competitor billing, the default competitor count, and that thin markets may return fewer competitors and cost less. These are material operational details not captured by readOnlyHint, openWorldHint, or destructiveHint.

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 front-loaded with the use case, then states what is returned, then explains cost. Every sentence carries actionable information and there is 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?

With an output schema present and full schema description coverage, the description still provides the key operational context an agent needs: purpose, return structure at a high level, default behavior, and credit cost. Nothing important appears missing for correct selection and invocation.

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 100%, so the baseline is 3, but the description adds useful meaning for the competitors parameter by explaining default count, billing per actually returned competitor, and cost variability in thin markets. It does not further clarify business_name, location, or keyword 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?

The description states a specific comparison task: comparing your business vs local competitors on rankings, reviews, ratings, and Google Business Profile completeness. This clearly distinguishes it from sibling tools focused on single-business audits, reviews, or backlinks.

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 a clear usage condition with 'Use when comparing your business vs local competitors...' but does not name when to avoid it or explicitly route to alternative sibling tools such as local_audit or reputation_audit.

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 (readOnlyHint, openWorldHint, destructiveHint), so the lower bar applies. The description adds substantial beyond-schema context — organic-only ranking, credit pricing per grid size, refunds for failed points, 30-60s wait, job_id fallback, and 24h caching — making it unusually transparent for a read 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?

Front-loaded with the use case, then cost, then the timeout/retry path — every section earns its place. It is dense and long, but the density is functional rather than padding; only the return-field enumeration is more verbose than strictly necessary.

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, yet the description fully enumerates the return fields (grid, grid_points, center, average_rank, atrp, solv, etc.), plus cost, timing, and the async fallback — everything an agent needs to call and interpret the tool.

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 100%, so baseline is 3. The description adds real value by mapping grid sizes to credit costs (18/50/98/162 cr) and explaining include_listings triggers the top-20 competitor listings, beyond what the schema field text states.

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?

Opens with a specific use condition (mapping where a business ranks across a geographic area) and clarifies scope: public Google Maps organic rankings only, top 20, ads skipped. An agent can distinguish it from geogrid_status, which is explicitly named as the follow-up 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?

States when to use it, when to instead call geogrid_status ('if the result is not ready in time'), and that re-calling with same inputs returns a cached lookup rather than a duplicate run. Also mandates confirming cost with the user first.

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 it read-only, open-world, and non-destructive, but the description adds substantial context: FREE unlimited polling, the full pending/running/complete/failed lifecycle, refunds on failure, and per-point error/refund semantics. No annotation contradiction.

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 trigger in the first sentence, then moves through statuses, error/refund handling, and grid-reading notes in short labeled chunks. The length is justified by async polling and interpretation guidance, 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?

Even with an output schema present, the description supplies interpretive rules the schema cannot convey: 0 means not found, and average_rank/found_in count only found points. Combined with annotations and complete parameter coverage, nothing needed 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?

There is only one parameter, and schema coverage is 100% with a description that already explains job_id as the value returned by geogrid_scan. The description repeats that meaning but does not materially extend it, so the baseline 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?

States a specific verb and resource: collect the grid from a geogrid_scan job that returned a job_id. It also names the exact sibling scenario that triggers it, so an agent can distinguish it from geogrid_scan and unrelated status tools.

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 says to use it only when geogrid_scan returned a job_id instead of a result, notes that most scans never need this tool, and encourages polling because it is free. That covers both when to use it and when not to.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value beyond them by disclosing the cost model ('Free (0 credits)') and the exact content of the response breakdown, including the spending order of the two credit pools — information an agent needs to interpret 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?

Three short sentences, front-loaded with what is returned, then when to call it, then cost. Each sentence carries distinct information — payload contents, usage trigger, and free-call status — with no restatement of the name or 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?

A zero-parameter, read-only, free tool with an output schema that documents the return shape and annotations that cover the safety profile. The description adds the two things structured fields cannot: the semantic meaning of the two credit pools and the recommended call timing.

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?

Zero parameters, so there is nothing to document beyond what the empty schema already conveys; baseline applies. The description correctly avoids inventing or implying any inputs.

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?

Names a specific verb and resource ('Returns available credits') and enumerates the exact breakdown: monthly plan allowance (spent first), never-expiring wallet, daily spending cap, plan, and environment. No sibling tool in the list does anything similar, so an agent can distinguish it immediately.

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 concrete trigger — call it before multi-step or expensive analyses to confirm sufficient credits. It does not state when the call is unnecessary (e.g., cheap single-shot queries), but with no competing sibling for balance information there is little ambiguity left.

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?

Goes well beyond the readOnly/openWorld annotations: cost (1 credit per 10 reviews), expected latency (10-30s), a silent-failure mode for ambiguous lookups, and the fact that the default language machine-translates. That is exactly the context an agent needs to plan a call and interpret an empty 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?

Front-loads the trigger, then return shape, then the parameter caveat, then cost and latency. Every sentence carries a distinct constraint; nothing is restated from the schema without a reason.

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 a full schema and output schema, the remaining unknowns are the ones that actually cause bad calls — cost, latency, ambiguous-match emptiness, translation behaviour — and all four are covered.

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 100%, so the description's job is only to add meaning. It usefully elevates place_id to a recommended override and flags that the language default translates rather than returns originals — real added value — but sort, limit and business_name get no treatment. Marginally above the baseline.

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 — reading review text and owner replies — plus the intended analysis use (sentiment, reply auditing) and the exact fields returned. It never names its closest siblings (multi_platform_reviews, review_velocity), so an agent must infer that this one is Google-only and text-level rather than aggregate or velocity.

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?

Opens with an explicit "Use when..." trigger and gives a concrete operational rule: pass place_id for multi-location brands because name+location can silently return empty. It stops short of naming when to prefer a different review tool, so there is no true exclusion 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?

Adds substantial behavior beyond annotations: it is free, null bodies are not errors, and response_data_omitted="not_stored" intentionally does not infer one of four possible causes. This is exactly the kind of operational context annotations do not provide.

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 purpose and cost, then explains id sourcing, then addresses the null-body edge case. Every sentence carries useful information without repetition.

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 an output schema, annotations covering read-only safety, and a fully documented parameter, the description supplies the remaining important context: cost, id source, and non-error null body behavior.

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 has 100% description coverage and documents the single id parameter. The description repeats that the id comes from a previous response or history_search but does not add syntax or format detail 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: returns one past call in full, including the response body as originally returned. It explicitly distinguishes this from history_search by saying where the id comes from and frames the value as reading an already-paid-for answer.

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?

Explains when to use it: with a request_id from a previous response or an id from history_search. It also gives the alternative implicitly by saying this reads an answer already paid for rather than buying it again.

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 read-only, non-destructive, closed-world, so the description correctly spends its words elsewhere: zero-credit cost, full response retention, the sandbox-key scoping caveat, the logging-disabled caveat that silently empties all param filters, and the fact that response bodies are deliberately excluded. These are exactly the behavioral traps an agent could otherwise fall into.

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 cost-saving instruction before any mechanics, and each paragraph covers a distinct concern (why, filters, return shape, composition). It runs long for a search tool and the 'did we already check this?' example list is slightly padded, but nothing is genuinely wasted.

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 12-parameter search tool with an output schema, the description supplies the pieces structured data cannot: free-vs-paid framing, retention guarantees, account-state caveats, matching semantics, and the request_id handoff to history_get. 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the conceptual semantics — filters match the parameters of the original call, values match exactly rather than as substrings ('best plumber' ≠ 'best plumber near me'), and endpoint is the one substring field. It doesn't touch from/to, sort, order, page or limit, but the schema handles those.

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 ('finds calls this account has already made') and immediately scopes it to request history rather than response bodies, explicitly routing to history_get for the payload. An agent can distinguish it from the dozens of live-endpoint siblings without opening a 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 an explicit imperative ('USE THIS BEFORE BUYING DATA AGAIN'), names the concrete question shapes it answers, states the cost consequence of the alternative (re-running the original endpoint charges full price), and names the complementary tool (history_get) with the exact composition pattern. Both when-to-use and when-not-to-use are covered.

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, and destructiveHint=false, so the safety profile is covered. The description adds meaningful non-annotation context — the credit cost (4 credits) and the returned fields — which helps the agent understand the operational tradeoff.

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 tightly written sentences: usage condition, return shape, and cost. It is well front-loaded with no filler, and every sentence earns its place.

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 tool with a full input schema, annotations, and an output schema, the description covers the core purpose, result fields, and cost. It could be slightly richer about how ranking is determined or prerequisites, but nothing essential for correct invocation 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds no parameter-level guidance beyond what the schema provides, making the baseline score appropriate.

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 outcome — finding the best local keywords based on difficulty vs current rank — which distinguishes it from generic sibling tools like keyword_suggestions or search_volume. It does not explicitly name alternatives, but the purpose is concrete and agent-actionable.

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?

Begins with an explicit usage condition ('Use when finding...') tied to the ranking-vs-difficulty scenario, giving clear context for selection. It does not mention when not to use it or name sibling alternatives, so it falls short of the top score.

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 read-only, open-world, non-destructive, so the safety profile is covered; the description still adds substantial context the annotations cannot express — credit cost band (10-116, scaling with keyword count), the 1000-keyword cap, country-level volume scoping, and that null means no data rather than zero. That is exactly the kind of extra context that earns full marks against an annotated 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?

Front-loaded with the trigger condition and the sibling contrast, and every sentence carries information (output fields, cap, cost, null semantics). The one long parenthetical enumerating backlink fields is dense and slightly hard to scan, which keeps it from a 5.

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?

Covers limits, cost, scoping caveats, and null handling, and the tool has an output schema so return shapes need not be spelled out — yet the description still previews the key fields. An agent has everything needed to decide and call 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 100%, so all three parameters are already documented and the baseline is 3. The description reinforces the 1000-keyword limit and the country-level scoping of location, but adds little syntax or format detail beyond what the schema states, and includes no guidance on language fallback behavior.

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?

Names a specific resource (keywords) and enumerates the exact payload it returns: volume, CPC, competition, keyword_difficulty, search_intent, and the averaged backlink profile. It explicitly contrasts itself with the sibling search_volume, so an agent can separate the two without opening either 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?

Opens with a trigger condition ("Use when you have keywords and want the full picture on them") and names the alternative plus the precise condition that selects it ("use search_volume instead when the city/state number is what matters"). Both when-to-use and when-to-use-something-else are stated.

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 it as read-only, non-destructive, and open-world. The description adds valuable behavior not in annotations: the 20-credit cost and the important caveat that volume data is country-level only, with location_used indicating actual scope.

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 three sentences, front-loads the use case, lists return fields, and clearly flags the critical volume-scope caveat and cost. Every sentence carries operational value.

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 that annotations cover safety, the schema documents all parameters, and an output schema exists, the description supplies the remaining operational essentials: return metrics, cost, and the country-level volume limitation. Nothing material appears missing for correct invocation.

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 100%, so the baseline is 3. The description adds meaningful semantic context about the location parameter's limitation: volumes are country-level and location_used should be checked for actual scope, which is more than the schema states.

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: reverse-engineering what keywords a competitor domain ranks for, and names the returned metrics. This clearly distinguishes it from generic keyword suggestion or search-volume tools in the sibling list.

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 usage context: 'Use when reverse-engineering what keywords a competitor domain ranks for.' However, it does not name alternatives such as keyword_opportunities or keyword_overview or state when not to use it.

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 description adds substantial behavior beyond the readOnly/openWorld annotations: it explains the national database source, Google Ads localization for city/state scopes, country fallback, location_used and location_alternatives fields, national keyword_difficulty, null search_volume semantics, and a 92-credit cost.

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 front-loaded with the usage condition and remains dense with relevant operational details. It is appropriately sized for the tool's complexity, though the single long paragraph could be easier to scan.

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 the output schema and annotations, the description covers the key behavioral context an agent needs: data source, localization scope, fallback behavior, null handling, alternative tool routing, and cost. Nothing material appears 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?

Schema coverage is 100%, so the baseline is 3. The description earns an extra point by explaining how the required location parameter affects volume_scope, fallback behavior, and related output fields, though it does not elaborate on limit, language, or include_seed_keyword 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?

The opening sentence states a specific verb and resource: generating new keyword ideas from a seed keyword. It also distinguishes the tool from search_volume for users who already have keywords and need metrics.

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 when to use this tool and gives search_volume as the alternative for existing keywords. It does not clarify when to choose related_keywords, keyword_opportunities, or keywords_for_site, so the sibling routing guidance is good but not exhaustive.

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?

Beyond the annotations, the description discloses important behavior: the in-progress week/month is omitted, interest data is country-level with no city/state granularity, peak_month can be null, and the tool costs 9 credits. These are exactly the operational details an agent needs to invoke it correctly.

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 front-loaded with the usage condition and keeps important caveats near the end. It is dense but largely purposeful, though it enumerates return fields even though an output schema exists.

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 the output schema and annotations, the description is complete: it covers when to use the tool, supported periods, cost, return shape, missing-data behavior, and the critical country-level limitation. An agent has enough context to select and 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?

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning by clarifying the period options and default and warning that location resolves to country-level scope via location_used. It also indicates one series is returned per keyword.

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 clearly states that the tool checks whether a keyword is rising, stable, or declining over time, and it summarizes the returned trend data. It does not explicitly differentiate this from sibling keyword tools such as search_volume, keyword_overview, or keyword_opportunities.

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 a clear usage context: use when checking keyword trend direction over time. It also notes the supported periods, default period, credit cost, and country-level limitation, but it does not name alternatives or state when not to use this tool.

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?

Beyond the readOnly/openWorld/destructive annotations, it discloses cost (50 credits), latency (15-45 seconds), and async execution — three operational traits an agent cannot get from structured fields. It also names the concrete return fields, so the agent knows the shape of the result without an output 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 sentences, each doing distinct work: trigger, return payload, and cost/latency warning. The most decision-critical constraint (expensive, confirm first) is placed after the payload but before the timing caveat, and nothing is redundant.

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 two-required-param aggregator with no output schema, the description supplies the trigger, the full list of returned metrics, the credit cost, and the expected wall time. An agent has everything needed to decide whether to call it and to warn the user.

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 100% with both parameters documented ('City and state', 'Business name'), so the schema already carries the semantic load. The description adds no format guidance or constraints on business_name/location (e.g., disambiguation, use of location_search first), 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?

States a specific verb and composite resource: 'comprehensive local SEO check: SERP + profile + reviews + competitors in one call'. It enumerates exactly which data domains are bundled, which distinguishes it from single-signal siblings like local_pack, organic_serp, google_reviews, and competitor_gap.

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?

'Use when running a comprehensive local SEO check' gives a clear triggering context, and the 'in one call' framing implicitly signals the alternative is running the individual tools separately. It also adds a procedural gate: 'confirm with user first' due to cost. It stops short of explicitly naming the narrower sibling tools or stating when not to use it.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered; the description adds genuinely new context by disclosing the 10-credit cost and the shape of the result (sub-scores with score/max/detail plus percentile). It does not mention permission or quota nuances beyond the flat credit price, keeping it short of a 5.

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 trigger condition and immediately followed by return shape, then a tracking hint and cost. No filler, though the 'Good single metric to track over time' line is the softest and could be folded into the usage sentence.

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 an output schema present, the description needn't explain return values, yet it summarizes them usefully; combined with annotations covering safety and the disclosed credit cost, an agent has enough to decide and call correctly. The only gap is no guidance on when a more granular audit sibling is preferable.

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 100%, so business_name, location, and keyword are already documented at the field level. The description adds nothing about parameter behavior (e.g., how keyword alters the score versus defaulting to the business name), which is the baseline-3 case where the schema carries the load.

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+resource ('calculating a composite 0-100 local authority score') and enumerates the output components (ranking, reviews, profile, citations, percentile), so an agent knows exactly what this produces. It does not explicitly name a sibling it is not (e.g., local_audit or reputation_audit), so differentiation from the many audit tools is only 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?

'Use when calculating a composite 0-100 local authority score' and 'Good single metric to track over time' imply the usage context (a rollup/tracking metric versus detailed point-in-time audits), but there is no explicit when-not condition or named alternative to select instead.

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, openWorld, and non-destructive behavior. The description adds useful context beyond annotations: the output fields returned and a concrete cost of 2 credits.

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 usage condition, then lists return data, filter support, and cost in compact sentences with no waste.

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 annotations covering safety, an output schema present, and full schema descriptions, the description supplies the remaining decision-critical context: CID-vs-GPS distinction, return content, filter support, and credit cost.

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 100%, so parameter meanings are already documented. The description mentions the `min_rating` filter but adds no format or edge-case detail beyond that, making the baseline 3 appropriate.

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 capability: local listings with Google CID identifiers, and explicitly contrasts it with map-based GPS coordinate results. This lets an agent distinguish it from the `maps` sibling without opening schemas.

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 use condition — local listings with CIDs rather than GPS coordinates — and names the alternative `maps` scenario. It does not cover when-not-to-use relative to other local listing siblings, but the primary routing cue is explicit.

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 read-only, open-world, non-destructive operation. The description adds useful behavior beyond annotations: it states the credit cost, describes the returned fields, and explains depth and device effects. The only issue is that its stated default result count conflicts with the schema's default.

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 front-loaded with the core purpose and then efficiently covers output fields, depth, device, the `maps` distinction, and cost. It is appropriately sized and has no wasted 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?

An output schema exists, and annotations cover the safety profile, so the description does not need to carry the full burden. It is still mostly complete, but the incorrect default-result statement conflicts with the schema and leaves an agent unsure about how many results will be returned without setting depth.

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 100%, so the schema already documents keyword, location, depth, and device. The description adds some semantic context for depth and device, but it says the tool returns the top 3 by default while the schema says depth defaults to 20, creating a meaningful ambiguity.

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: checking where businesses rank in Google's local pack for a keyword. It also distinguishes the tool from the sibling `maps` tool by explaining that `maps` returns GPS coordinates and place_ids instead of CIDs.

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 implies the use case is local-pack rank checking and explicitly contrasts with `maps` for a different output shape. However, it does not say when to use this instead of other local or keyword tools such as `local_finder`, `organic_serp`, or `business_profile`.

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