Manifold MCP

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

Annotations already declare read-only, idempotent, non-destructive and open-world, but the description goes well beyond that: it discloses the 1-credit cost and 7-day cache, warns that impressions/spend are published as text ranges rather than numbers, and explains that reach, age splits and payers exist only for Facebook ads that ran in the EU/UK. It also flags the Google first_shown fallback and null case, which is exactly the kind of data-quality caveat an agent would otherwise misread as an error.

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 Use when / Not for / Returns / Cost / Example layout is front-loaded and scannable, and every caveat sentence earns its place. The long enumeration of return fields is the weakest part, since an output schema already exists and the field list duplicates it.

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 four parameters, full schema coverage and an output schema, the description supplies everything else an agent needs: cost model, cache duration, per-platform caveats and a working example. Nothing required 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 platform, id, dry_run and max_credits are already documented, and the description correctly does not repeat them. It does add practical meaning by giving a concrete example payload and by tying credit cost to the budget-guard parameter, though it never explains the platform-dependent id format (id vs URL) in its own words.

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 names a specific verb (retrieve one ad) and resource (a single ad from a platform's public library) and enumerates the substance it carries: creative text, destination, targeting and reach. The 'Not for' line explicitly separates it from ads_search_ads and ads_get_advertiser_ads, so the agent can route 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?

'Use when: reading the offer and the call to action behind an ad you found in a list' gives a concrete triggering condition tied to a prior step. The 'Not for' clause names both set-level alternatives by name and points to the platform transcript tool for video content, covering the main wrong-turn paths.

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

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

Annotations already declare readOnly/idempotent/openWorld/no-destructive, so safety is covered; the description goes further with cost ('1 credit per page, or 25 on google with details'), 24-hour caching, and a data-quality caveat that impressions and spend are published ranges returned as text. It also explains that 'versions' means near-identical copies Meta groups, which is a scaled-signal the agent would otherwise misread.

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 purpose sentence followed by clearly labeled Use when / Not for / Returns / Cost / Example blocks — easy to scan. The long enumeration of return fields is partly redundant with the existing output schema, though the annotations on versions and text-formatted spend still earn their space.

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 paginated, multi-platform, credit-charging read tool with 8 parameters, the description covers selection rationale, pagination cursor presence, platform-specific limits (no country on tiktok, active_only facebook-only, details google-only), cost, caching, and an example. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by tying the details flag to its 25-credit tradeoff and by giving a concrete invocation example that shows the expected advertiser value shape for google. It does not add much beyond the schema for cursor, country, active_only, max_credits, or dry_run.

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 ('Every ad one advertiser is running, from a platform's public library') and immediately scopes it to a single advertiser. It differentiates from siblings by naming ads_search_ads for cross-advertiser sweeps and ads_get_ad for one creative in full, so the agent can route correctly without reading 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?

Explicit labeled 'Use when' scenario (competitor teardown: what they run, since when, with what offer) and a 'Not for' section that names both alternatives and the condition that selects each. Nothing is left to inference about when this tool is the right call.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, but the description adds economics and semantics annotations cannot: 1 credit per page, 24-hour caching, and the fact that impressions and spend are published ranges returned as text. It also explains that `versions` signals near-identical copies (a scaling signal), which is real interpretive context.

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

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

Front-loaded purpose followed by use/not-for/returns/cost/example in a scannable order, with no filler. The Returns sentence is a long field enumeration that partly overlaps the output schema, costing a little tightness.

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 a mutation-free search tool with an output schema and full annotation coverage, the description covers purpose, alternatives, cost, caching, and key output caveats. It is slightly redundant with the output schema in the field list, and does not mention pagination mechanics (cursor) beyond what the schema states.

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% and the description largely echoes what the schema already says (Google being advertiser-keyed appears in the platform param description too). The embedded example call does illustrate a valid parameter combination (platform + query + active_only), which adds modest value, so baseline 3 applies rather than a penalty.

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 the specific resource (ads in a platform's public library) and the search keys (keyword or brand), and explicitly separates itself from ads_get_advertiser_ads (full advertiser set) and ads_search_advertisers (Google, advertiser-keyed). An agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use framing ("what ads is this category running", competitor angles and offers) plus three explicit not-for branches with named alternatives: ads_get_advertiser_ads, ads_search_advertisers for Google, and platform-native organic search. Both inclusion and exclusion conditions are spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds behavior annotations cannot express: a cost of 1 credit and a 7-day cache window, which matters for repeat-call planning. It stops short of stating result-count limits or pagination, keeping it off 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 the purpose, then uses labeled blocks (Use when, Not for, Returns, Cost, Example) with no filler. Every line carries information an agent needs to select and call the tool.

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 lookup with a full output schema and full annotation coverage, the description supplies everything remaining: purpose, routing, cost, caching, and an example. Nothing needed to invoke 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 baseline is 3. The description adds meaning beyond the schema by explaining the rationale behind the fixed platform value (only Google keys its library by advertiser) and by supplying a concrete example payload that shows query/region usage together. It does not explain dry_run or max_credits, which the schema handles.

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 – finding advertisers matching a brand name in Google's ad library, returning their ids – and names the sibling it must not be confused with (ads_search_ads for other libraries). An agent can pick it out of a crowded sibling list 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?

Has explicit 'Use when' (before ads_get_advertiser_ads, because that library is keyed by advertiser id and a brand has one entry per region) and explicit 'Not for' routing the agent to ads_get_advertiser_ads for ads themselves and to ads_search_ads for other libraries. This is the strongest form of when/when-not guidance.

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

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

Annotations cover read-only/idempotent/open-world, and the description adds genuinely new operational facts: ~17 live fetches against the origin, no crawl and no LLM call, 0 credits but rate limited, and a 1-hour cache. The 'policy' and 'unproven' tier definitions also disclose that some checks never fail, which prevents misreading a passing result as a positive signal.

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?

Well front-loaded: purpose sentence, then Use when / Not for / Returns / Cost / Example in a predictable order. The one cost is the lengthy Returns enumeration, which repeats detail an output schema already provides and inflates the definition; the tier vocabulary explanation, however, earns its space.

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 zero-cost, security-sensitive readiness scan, an agent needs to know scope (origin only), mutation risk (none), latency/caching behavior, and how to interpret non-failing checks — all present. The sample_page null case and the markdown/Accept-header edge case are also called out, leaving no meaningful ambiguity.

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 the schema already documents it at 100% coverage ('A domain or URL. Every fetch goes to its origin.'), so the schema carries the semantics. The description's example {"target": "example.com"} confirms format but adds little beyond what the schema field states; 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?

Opens with a specific verb-and-resource framing: whether a site is set up for AI answer engines, measured from ~17 live fetches of its origin. It then enumerates the exact dimensions checked (robots.txt per AI crawler, WAF/CDN blocking, raw-HTML content, noindex, freshness, sitemap, llms.txt), which makes it unmistakable against everything else in the catalog.

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?

Has an explicit 'Use when' block with four realistic trigger phrasings (readiness, GPTBot blocking, Cloudflare blocking, llms.txt) and a 'Not for' block that routes three distinct cases to named siblings: aeo_run_ai_answers for engine answers, seo_run_technical_crawl for a full audit, seo_get_page for one page's tags.

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 only say read-only/open-world/idempotent; the description adds the async task_id + get_task pattern, non-determinism of live answers, 30-day retention with no caching, per-engine credit costs, no charge for failed cells, and the distinction between app-surface engines (chatgpt, gemini) and API-backed ones (claude, perplexity). It even flags that named_brands can miss brands and that answer null means no AI answer was shown.

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?

Dense but front-loaded: purpose, then Use when / Not for, then Returns, then Cost, then Example. The Returns block partially restates an existing output schema, though its per-engine caveats justify most of the length; a few clauses 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 a 7-parameter, async, multi-engine, credit-metered tool, the description covers what it does, when to use it, how to retrieve results, what can be missing per engine, cost math, and a runnable example. An agent has everything needed to call it correctly and avoid budget surprises.

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 a point by attaching economics to the engines parameter (15 credits for claude, 6 for perplexity, 2 for chatgpt/gemini/ai_overview/ai_mode, default five engines = 27 credits) and by showing brands usage in the example. It stops short of explaining location/language/max_credits behavior 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?

Opens with a specific verb and resource: what AI engines answer for a prompt, plus the brands they mention and sources they cite. It immediately distinguishes itself from aeo_search_prompts, seo_get_serp and aeo_get_site_readiness, so an agent can route 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?

Has explicit 'Use when' cases with example phrasings (does ChatGPT recommend us for X, who do AI engines cite) and an explicit 'Not for' block naming three alternatives plus the condition selecting each. Nothing is left to inference.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses pricing (31 + 31 per 100 rows, 47 credits at the default 50 rows), a 7-day cache, and the important caveat that ai_search_volume is a People Also Ask proxy rather than query logs. It also disambiguates mentions_brand semantics for domain versus keyword inputs, which is behavior an agent could not infer from 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?

It is front-loaded and clearly sectioned (definition, Use when, Not for, Returns, constraint, Cost, Example), with no filler sentences. The long field-by-field Returns enumeration is somewhat heavy given an output schema already exists, though the per-field caveats do add meaning.

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 9-parameter, paginated, metered search tool with an output schema, the description covers selection, exclusivity of inputs, cost and budget behavior, caching, and interpretive caveats on key return fields — everything needed to call it correctly and interpret results.

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 89%, so most parameters are already documented, but the description adds a constraint the schema does not encode: exactly one of keyword or domain must be supplied. It also clarifies what mentions_brand means depending on which of those two inputs is used, and pairs the cost model with max_credits/dry_run 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?

The description gives a specific verb and resource — prompts observed in AI engine answers (ChatGPT or Google AI Overview) — and explicitly contrasts the concept with keywords, so an agent can tell it apart from seo_search_keywords and the other 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?

It names concrete triggering questions ("what do people ask ChatGPT about X", "which prompts mention our brand", baseline building) and an explicit "Not for" section routing to seo_search_keywords and aeo_run_ai_answers 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 declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description goes beyond them with a concrete cost model (5 + 5 per 100 rows, default 10 credits), a 7-day cache note, and the non-obvious exclusion of the target product itself, which are genuinely useful operational facts.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) make it scannable and front-loaded with the core definition. Every sentence carries information; the only near-redundancy is the Returns field, which largely restates 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?

With an output schema present, the return-value listing is technically optional but the ASIN-only caveat and the pointer to amazon_get_product for titles fill a real gap. Cost, caching and the self-exclusion rule round out an otherwise complete picture for a 7-parameter, paginated, credit-metered 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% and the schema already documents asin, limit, cursor, dry_run, language, location and max_credits in detail. The description adds a worked example {"asin": ..., "limit": 20} and ties row count to credit cost, but adds no semantics for cursor, dry_run or max_credits beyond what 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?

"Amazon products that compete with one product for the same searches, with how many they share and how each ranks" gives a specific resource, the basis of competition (shared searches), and the payload (shared count, rank). It is immediately distinguishable from sibling retrieval tools like amazon_get_product or amazon_get_sellers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description has explicit "Use when" phrasings tied to real user intents and an explicit "Not for" clause naming two alternatives: amazon_search_products for a single search's results and seo_get_serp_competitors for web competitors. The routing decision requires no 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds genuinely new behavior: credit pricing formula with a worked example (5 + 5 per 100 keywords), a 7-day cache, and null volume meaning 'no data'. It stops short of describing failure modes or rate limits beyond cost, which the schema partially covers via BudgetExceeded.

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 summary sentence followed by labeled Use when / Not for / Returns / Cost / Example blocks. Every line carries actionable information — the cost example and the JSON call example both earn their space — with no filler prose.

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 batched, metered read tool with an output schema, the description covers purpose, routing, cost, caching, and the shape of a notable null case. An agent has everything needed to decide, budget, and call it correctly.

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

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

Schema coverage is 80%, so the schema carries most parameter documentation. The description still adds meaning beyond it: the 1,000-keyword cap, that output order matches input order, and that a null volume signals no data. It does not explain what location or language change about the returned volume, which is the one semantic gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource+scope: 'Monthly Amazon search volume for up to 1,000 keywords you already have, in the order given.' It explicitly differentiates from the two nearest siblings (seo_get_keyword_metrics for Google volume, amazon_search_keywords for discovery), so an agent can pick correctly 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?

Contains explicit 'Use when' triggers (sizing Amazon demand, comparing to Google demand) and an explicit 'Not for' clause that names the correct alternative tool for each excluded case. This is the full when/when-not/alternative triad.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description goes further with a credit cost formula (5 + 5 per 100 rows), a 7-day cache notice, and a note that dry_run costs nothing. It also discloses result ordering (by volume, descending) and that rank counts both organic and sponsored rows, which materially affects interpretation.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) with the purpose sentence first and zero filler. Each line carries distinct information an agent needs to decide or to budget the call.

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 seven parameters and a cost-bearing call, the definition covers the decision boundary, the return shape, pagination entry point, budget guard, and pricing. An output schema exists, yet the brief row summary still helps the agent reason about ranking semantics rather than being redundant.

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 including cursor, dry_run, max_credits, language, and location is already documented in the schema, making 3 the baseline. The description adds only a worked example ({"asin": ..., "limit": 50}) and the 'default 100 rows = 10 credits' cost tie-in; it says nothing extra about cursor paging, max_credits refusal behavior, or language/location effects.

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: the Amazon searches a product ranks for, plus volume, rank, and organic/sponsored type. It explicitly distinguishes itself from seo_get_ranked_keywords (Google) and amazon_search_keywords (new keyword ideas), so an agent can separate it from the nearest 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?

Provides a 'Use when' block with three concrete phrasings an agent might hear ('what does this ASIN rank for', 'which searches bring competitor's product its sales', title keyword selection) and a 'Not for' block naming both alternatives and the condition that selects each. Nothing is left to inference.

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

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

The annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely new operational context: cost of 2 credits and a 1-day cache, which matter for budgeting repeat calls. It does not discuss failure modes or the partial-result behavior of the optional dry_run/max_credits path, 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?

The labeled Use/Not for/Returns/Cost/Example blocks make it front-loaded and scannable, with no filler prose. The Returns line is largely a restatement of fields already present in the output schema, which is the only redundant bulk.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-resource fetch with a full output schema, the definition covers scope, routing, cost and a call example. Minor gaps: dry_run and max_credits are never mentioned in the description, so an agent skimming only the prose would miss the free-estimate and budget-guard affordances.

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 the baseline is 3 and the schema already explains asin format, dry_run cost-free estimation, language, location and max_credits budget refusal. The description adds only the concrete example payload {"asin": "B0B41YH9B6"}, which is useful but does not deepen meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line gives a specific verb and resource (one Amazon product, keyed by ASIN) and enumerates exactly what is returned: title, price/discount, rating, availability, category path, About-this-item, spec table, variations, images. This clearly distinguishes it from amazon_search_products (many) and amazon_get_sellers (who else sells it).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit 'Use when' trigger phrases and an explicit 'Not for' section that routes two adjacent needs to named siblings: amazon_get_sellers for competing sellers, amazon_get_keywords for ranked search terms. It also states reviews are not available for Amazon, closing a gap an agent would otherwise probe.

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 annotations (readOnly/openWorld/idempotent) by disclosing the 2-credit cost, a 6-hour cache window, and a non-obvious output behavior: has_featured_offer is false when no Buy Box holder exists and rows then start at rank 2. It also notes seller_url is null for Amazon itself, which prevents misreading the response.

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?

No wasted sentences: purpose first, then Use when / Not for / Returns / Cost / Example in a consistent front-loaded pattern. Each line adds distinct information despite being dense.

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?

Complete for a five-parameter read tool: it explains purpose, when to choose it, when not to, the return shape, cost and caching, plus a working example. With an output schema present, no return-value explanation 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 the schema already documents asin format, dry_run, language, location, and max_credits. The description adds an example ASIN and mentions credit cost, but does not clarify dry_run's zero-cost estimate mode or how max_credits interacts with the stated 2-credit price. Baseline 3 is correct when 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?

States a specific verb and resource ('Every seller offering one Amazon product') and immediately scopes the output to price, condition, shipping origin, delivery, and Buy Box ownership. This clearly distinguishes it from amazon_get_product and shopping_get_sellers by name.

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?

Provides explicit 'Use when' triggers ('who sells this ASIN', 'are resellers undercutting our price', 'is Amazon itself selling this') and an explicit 'Not for' clause routing to amazon_get_product for the listing and shopping_get_sellers for other stores. Nothing is inferred.

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/idempotent annotations by disclosing a pricing formula (5 + 5 per 100 rows), the default spend (10 credits at 100 rows), and a 7-day cache. It does not mention result ordering, data freshness beyond the cache window, or failure modes such as BudgetExceeded (which only the schema hints at), so it stops 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?

Labelled blocks (Use when / Not for / Returns / Cost / Example) make it skimmable and front-load what the tool does before constraints. Every line carries decision-relevant information; nothing is restated from 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?

For a 7-parameter, cost-incurring, network-open tool the description covers purpose, alternatives, spend, caching and output shape, while the rich schema and output schema carry the rest. An agent has everything needed to decide to call it and how much it will 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 seed, limit, cursor, dry_run, language, location and max_credits are all documented structurally. The description's only addition is a worked example pairing seed with limit, which is a marginal illustration rather than new semantic information — 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 ('Amazon search ideas around a seed, from Amazon's related searches') plus the metric returned ('monthly Amazon search volume'). It is immediately distinguishable from amazon_get_keywords and amazon_search_products by naming the discovery-of-related-searches scope.

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?

Contains explicit 'Use when' triggers (expanding around a seed, building a listing/ads keyword list) and explicit 'Not for' exclusions that name both alternatives and the condition selecting each: seo_search_keywords for Google, amazon_get_keyword_metrics for volume on keywords you already hold.

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 the return shape (keyword, results_count, rows with rank/type/asin/price/rating/offers, related_searches), pricing behavior (2 credits per 100 results, default 100 = 2 credits), and caching (1 day). These details materially help an agent understand cost and output behavior, and they do not contradict the readOnly/idempotent/openWorld 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 front-loaded with the core purpose, followed by clearly labeled 'Use when', 'Not for', 'Returns', 'Cost', and 'Example' sections. Every sentence adds useful information for selection or invocation, with no apparent 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?

Given the tool's complexity, six parameters, existing output schema, and annotations, the description is complete enough for an agent to call it correctly. It covers purpose, alternatives, return fields, cost, caching, and a concrete invocation example, leaving no significant gaps.

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

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

Schema description coverage is high (83%), so the schema already documents most parameters including depth, dry_run, language, location, and max_credits. The description's cost note and example reinforce depth behavior, but they do not add substantial new meaning beyond the schema's parameter 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?

The description states a specific verb and resource ('Amazon's results page for a search') and defines the scope: organic and sponsored products in order with price, rating, reviews, bought-past-month, and badges. It also explicitly distinguishes itself from siblings by naming amazon_get_product, shopping_search_products, and amazon_get_keyword_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 gives explicit when-to-use examples ('who ranks on Amazon...', 'which brands buy Amazon ads...', 'what do top products cost') and a separate 'Not for' section routing to the correct alternative tools. This leaves little ambiguity about when to choose this tool over siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new operational context: 0 credits, cached for 1 day, and a warning that the result is several hundred rows that should be narrowed with custom or category. The only gap is pagination behavior (the cursor parameter is never mentioned), which the schema covers only mechanically.

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 one-line definition followed by labeled Use when / Not for / Returns / Cost blocks, which makes it scannable. The Returns paragraph restates the output schema in detail and is the one section that could be trimmed without losing agent-relevant 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?

Given an output schema and full annotation coverage, the description supplies what structured data cannot: the decision rule versus the sibling tool, the cost/cache profile, and the volume expectation. An agent can select and call this correctly with no further reading.

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 property, limit, and cursor are already documented and the baseline is 3. The description adds only a usage example showing limit=1000 and advice to filter rows, but 'custom' and 'category' are result fields, not input parameters, so no real input semantics are added.

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 resource ('every dimension and metric one Google Analytics 4 property reports') plus the key value-add ('the api_name analytics_get_report takes'). That framing immediately distinguishes it from the sibling analytics_get_report and from analytics_list_properties.

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?

An explicit 'Use when' block enumerates four concrete triggers (uncommon field, custom dimensions, verifying a conversion/event-scoped name, recovery after a rejected field) and a 'Not for' clause routing to analytics_get_report. When-to-use, when-not, and the alternative are all named.

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, idempotent, non-destructive and open-world, but the description adds real behavioral context beyond them: cost of 0 credits, 1-hour caching, ~1 day data settling, Google privacy thresholding, (other)-row folding, rate scaling of 0-1, and the ordering rule that compare_start_date and compare_end_date must be supplied together or not at all.

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 purpose sentence, then labeled sections (Use when / Not for / Returns / Cost / Example) with no filler. The Returns section is dense but every clause carries semantics an agent would otherwise get wrong, such as TYPE_SECONDS and 0-1 rate scaling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, nested-filter tool with an output schema, the description covers routing, cost, caching, comparison pairing, and result semantics including thresholding caveats. Even though an output schema exists, the added interpretation of metric_types, currency_code, and rates is materially useful and nothing an agent needs to call it correctly 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 still adds value by stating the compare_start_date/compare_end_date pairing constraint in both directions, explaining the row shape keyed by api_name with dateRange markers under comparison, and providing a full worked example payload. It does not, however, elaborate on filters or order_by semantics 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: a GA4 report from the user's own property, with metrics by dimensions over a date range plus optional comparison range. It immediately differentiates itself from console_get_search_analytics and seo_get_traffic_estimates, so an agent can tell the three apart 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?

Has an explicit 'Use when' block with concrete question phrasings (traffic last month, sessions by channel, which pages convert, traffic drop vs prior period) and an explicit 'Not for' block naming the two sibling tools that handle Google search queries and non-owned sites. Nothing is left to inference.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the NotConnected failure mode and its connect_url recovery path, the zero-credit cost, a shared 60 calls/minute workspace limit, and a 1-hour cache. These are operational traits an agent cannot infer from annotations or an empty 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?

Front-loaded with the resource definition, then segmented into Use when / Not for / Returns / Cost / Example blocks. Every line carries operational information; nothing is redundant filler despite the length.

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?

Although an output schema exists, the description adds the key field-level guidance an agent needs (property is the id to pass on, in properties/123456789 form) plus the account pairing and property_type enum values. Combined with error handling and cost, nothing required to invoke this 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?

With zero parameters and 100% schema coverage there is nothing to disambiguate, and the `{}` example confirms the call takes no arguments. No additional parameter meaning is needed, so this sits at the no-params baseline rather than earning a 5.

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 names the specific resource (GA4 properties readable by the workspace's connected Google account) and its scope (with the owning account). It also explicitly positions itself as the entry point that the other analytics tools depend on, so an agent can distinguish it from analytics_get_report and analytics_get_fields 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?

Provides an explicit 'Use when' block with three concrete triggers, including natural-language user phrasings and the 'before any analytics_get_* call' prerequisite. The 'Not for' block routes two named alternatives (console_list_properties for Search Console, seo_get_traffic_estimates for unowned-site traffic), which is exactly the when-not guidance needed among 90+ siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds cost (1 credit), caching (1 day), latency (up to a minute), and null semantics for absent fields. It also discloses provider-specific quirks (App Store promotional text prefix, sometimes-null category, Google Play often-null version), which the agent could not learn from 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?

Header-labelled sections (Use when / Not for / Returns / Cost / Example) are front-loaded and scannable, with no filler sentences. The Returns block is the weakest part: since an output schema exists, re-listing every field and its null semantics is partly redundant, though the platform-specific caveats inside it are genuinely new 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 paid, cached, open-world lookup tool it covers everything an agent needs to decide and call correctly: triggers, exclusions, cost, latency, budget, output shape and provider asymmetries. 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 store, app_id, language, location, dry_run and max_credits are already fully documented in the schema; the description adds no meaning beyond the schema for those params. The worked example reinforces the app_id/store shape but does not cover the optional parameters such as dry_run or max_credits.

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+scope ("One app's store listing") and immediately enumerates the fields returned, so the agent knows exactly which resource this fetches. It is unambiguously distinguishable from apps_get_reviews, apps_get_keywords and apps_search_apps.

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?

Provides a concrete "Use when" list of natural-language triggers and a "Not for" block that names three alternatives (apps_get_reviews, apps_get_keywords, apps_search_apps/apps_get_top_charts) with the condition that selects each. No inference is required.

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, idempotent and non-destructive, but the description adds what they cannot: a credit formula (5 + 5 per 100 rows, default 10 credits), 7-day caching, a US/English-only data restriction, that the queried app is excluded from results, and that rows carry ids only. Those are exactly the facts that change how an agent plans a call.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) make it scannable and front-loaded with purpose. The opening sentence is dense and the Returns line is a run-on field dump, so a little trimming is possible, but almost every clause carries 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?

An output schema exists, yet the description still supplies the things it doesn't cover: cost, caching, geographic/language coverage, id-only rows and the apps_get_app follow-up, plus a dry_run path. For a 6-parameter paid tool, nothing an agent needs in order to 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 the baseline is 3, but the worked example pins down the enum value and id format in combination and makes the limit-to-cost tradeoff concrete ('limit': 20). It stops short of explaining cursor paging or max_credits interplay beyond what the schema already says.

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 plus the ranking basis: 'Apps that compete with one app for the same store searches, with how many searches they share and how strongly each ranks.' It also explicitly separates itself from apps_get_shared_keywords and seo_get_serp_competitors, so an agent can pick it 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?

Has an explicit 'Use when' block with three natural-language triggers and a 'Not for' block naming both the web-SEO alternative (seo_get_serp_competitors) and the near-sibling (apps_get_shared_keywords) 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 declare readOnly/idempotent/openWorld, yet the description adds substantial behavior an agent could not infer: result ordering (best rank first, then volume), a geographic/language restriction (US and English only), Google Play's thinner coverage, the meaning of NoData, seven-day caching, and the credit formula with the default cost. This is well beyond the annotation bar.

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 comes first, then labeled Use when / Not for / Returns / Cost / Example blocks — highly scannable with no filler. Each line carries a distinct, actionable fact (ordering, limits, pricing, a callable example).

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 though an output schema exists, the description usefully annotates field meaning (results_count as a thin-search signal, null on Google Play) and covers cost, caching, and pagination via cursor. For a six-parameter, credit-charging tool, an agent has everything needed to call it correctly and predict spend.

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 extra by tying 'limit' to the cost model (default 100 rows = 10 credits) and supplying a concrete literal example with store, app_id and limit values. It says nothing extra about cursor, dry_run, or max_credits beyond their schema descriptions, which keeps it from a 5.

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 names a specific verb and resource — 'Store searches an app ranks for' — and immediately qualifies it with the returned metrics (monthly search volume, the app's position). It is clearly distinct from a web-SEO tool and from apps_get_shared_keywords, so an agent can identify it without consulting 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?

The description gives explicit 'Use when' scenarios in the user's own phrasing ('what does competitor's app rank for in the App Store') and an explicit 'Not for' block that routes to named alternatives: seo_get_ranked_keywords for Google web searches and apps_get_shared_keywords for shared keywords. Both the positive and negative conditions 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description goes well beyond them with cost ('1 credit per 100 reviews', 'Default 100 = 1 credit'), a 6-hour cache, and a latency warning ('Can take up to a minute'). It also flags a real trap: ratings_count is the star histogram, 'not the reviews you can fetch', and explains that meta.rows_available is only set at the end of fetchable data. It stops short of describing error behavior beyond BudgetExceeded, which the schema already covers.

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?

Labelled sections (Use when / Not for / Returns / Cost / Example) make it scannable and front-loaded with the routing decision. The Returns block is dense and partly redundant with the existing output schema, so it is slightly longer than strictly necessary, but every line still carries usable 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 an 8-parameter, credit-metered, open-world read tool, the description covers selection, alternatives, cost, latency, caching, and the return shape's main caveats. With an output schema present it did not need to enumerate return fields, yet the annotations about rows_available and the ratings_count distinction add genuine value rather than padding.

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 88%, so the schema already carries most parameter meaning; the description adds the coupling the schema omits, tying limit to credit spend and showing a concrete worked call with sort/limit/store/app_id. Only the sort semantics ('newest or most relevant first') are clarified in prose, which is the one enum the schema leaves undocumented.

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 names a specific resource (user reviews of one app), the ordering options, and the fields returned (stars, text, app version, developer reply). It explicitly separates itself from apps_get_app (the listing) and shopping_get_reviews (physical products), 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?

The 'Use when' block gives concrete agent-facing intents ('what do users complain about in X's app', 'did the last release annoy people') plus a mining use case. The 'Not for' block names the exact sibling alternatives for the two most likely misroutes, leaving nothing 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the credit model (5 + 5 per 100 rows, default 100 rows = 10 credits), a 7-day cache, and a hard geographic/language restriction to United States and English only. It does not explain pagination behavior or what happens when an app pair yields no shared keywords, so it stops 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?

Labeled blocks (Use when / Not for / Returns / Cost / Example) with the core definition front-loaded in one sentence. Every line carries distinct information — no restatement of the name or 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 being present, the description still gives a compact return shape (keyword, volume, ranks) that tells the agent how to join results to input apps. Combined with cost, caching, scope limits, and an example call, nothing material is 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 baseline is 3; the description earns extra by clarifying that ranks[] follows 'the order the apps were given', which the schema does not state, and by pairing the example with the cost-per-limit relationship. Store naming and cursor mechanics are left entirely to 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 ('Store searches that two to twenty apps all rank for') plus the differentiator of side-by-side per-app positions. The cardinality constraint and the phrase 'all rank for' distinguish it immediately from single-app keyword 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?

Provides explicit 'Use when' phrasings tied to real questions ('where do we and competitor both rank', 'which store keywords does Teams beat Slack on') and an explicit 'Not for' section that routes to apps_get_keywords for one-app data and apps_get_competitors for competitor discovery.

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 (readOnly, idempotent, non-destructive), the description discloses pricing (1 credit per 100 rows), caching (1 day), worst-case latency (up to a minute), and the exact row shape. These are operational facts an agent cannot get from 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?

Labelled sections (Use when / Not for / Returns / Cost / Example) put scope first and details after, so an agent can stop reading early. Sentences are short and none are filler, though the chart variants are restated from the enum.

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 8-parameter, open-world read tool with an output schema, everything needed to call it correctly is present: cost model, budget behavior implications, latency, caching, category normalization, and a worked example.

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

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

Schema coverage is already 88%, so the schema carries most parameter meaning. The description still adds value by repeating the chart vocabulary in business terms and supplying a concrete example object showing store/chart/category combined with a normalized category id.

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 resource (a store's top chart) with the exact variants (free, paid, grossing, new) and scope (overall or one category), plus ordering (chart order). It also names the two siblings it is not: apps_search_apps and apps_get_app.

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?

Explicit 'Use when' examples map real queries to this tool, and 'Not for' sentences route keyword matching to apps_search_apps and single-app lookup to apps_get_app. Both the include and exclude conditions are spelled out.

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/idempotent hints by disclosing cost math (31 + 31 per 100 rows, 62 credits at default), 7-day caching, description truncation at 500 characters, and store-dependent ordering (installs on Google Play, ratings on App Store). The one gap is pagination/cursor behavior, which the schema covers only minimally.

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 definition, then clearly labeled Use when / Not for / Returns / Cost / Example sections that are easy to scan. Minor waste: 'Not the store's own search ranking' repeats what the 'Not for' line already said.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter search tool with an output schema, the description covers selection, return shape, pricing, result quality pitfalls, and a worked example call. Nothing an agent needs to invoke 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 baseline is 3, but the description adds real meaning: the OR-style title matching pitfall ('habit monitor' also returns flight monitors) and the mitigation of searching one distinctive word combined with category. It does not explain limit, cursor, dry_run, or max_credits beyond what the schema already 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?

States a specific verb and resource (title-matching app search across a store index) plus the payload shape: full listing with developer contact details. An agent can distinguish it from apps_get_top_charts and apps_get_app 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?

The 'Use when' block gives concrete example intents (finding CRM apps, sizing a category, building a maker list) and the 'Not for' block names the two alternatives that should be used instead (apps_get_top_charts for store rankings, apps_get_app for a single known app, explicitly flagged as 'much cheaper').

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 past the readOnly/idempotent/non-destructive annotations by disclosing cost (0 credits), scope (Bing only), cache TTL (6 hours), and the retention quirk that fixed issues stay listed a few days — that last one materially affects how an agent should interpret results. It does not cover rate limits or pagination behavior beyond the cursor field, so it falls short of the top mark.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) make it skimmable and front-loaded. The 'Returns' enumeration of rows fields largely restates the output schema, which is the one redundant block; the issue-code list is still useful since no enum exists in 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?

For a read-only, three-parameter, output-schema-backed tool, nothing an agent needs is missing: scope, cost, freshness, retention semantics, and routing to alternatives are all present.

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 limit, cursor, and property are already documented in the schema; the description only adds a single example object for property. It adds no semantics for limit or cursor beyond what the schema states, 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?

Opens with a specific verb and resource ('URLs Bing had trouble crawling on the user's property') and enumerates the issue classes covered (HTTP errors, redirects, robots.txt blocks, DNS, timeouts). It is unmistakable against console_inspect_url (single-URL) and seo_run_technical_crawl (own crawler).

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?

Explicit 'Use when' phrasing with three concrete user phrasings, plus an explicit 'Not for' that names the Google gap and routes whole-site crawling to seo_run_technical_crawl. The alternative is named with the condition that selects 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?

Goes well beyond the readOnly/idempotent annotations: it discloses Google's ~2-day data lag and 16-month retention, Bing's reduced query/page coverage and lack of date ranges, that totals differ across groupings due to Google aggregation, and that the tool is free and cached for 6 hours.

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 purpose sentence, then clearly labeled Use when / Not for / Returns / Cost / Example blocks. Despite its length every line carries distinct information — routing rules, caveats, schema quirks — with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with an output schema, the description still covers what an agent would otherwise miss: row shape and sort order, ISO alpha-3 country codes, ctr as 0-1 and 1-based position, and engine-specific data-freshness differences that affect how results should be interpreted.

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 already 100%, so every parameter including limit, cursor, engine, filters, dimensions and search_type is documented in the schema itself. The description adds an illustrative combined call showing property/dimensions/date range in practice, but no new semantics beyond the schema; 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 first sentence names a specific verb and resource and enumerates the exact metrics returned (clicks, impressions, CTR, average position) plus the supported groupings, so the tool is instantly distinguishable from siblings like seo_get_ranked_keywords or console_get_crawl_issues.

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?

Explicit 'Use when' phrasing with four concrete user-question examples, followed by a 'Not for' block that names the exact alternative tool for each excluded case (seo_get_ranked_keywords for non-owned sites, seo_get_keyword_metrics for volume/difficulty, console_inspect_url for indexing problems).

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 (readOnly, idempotent, non-destructive), the description discloses cost (0 credits), caching (10 minutes) and a crucial data quirk: urls_indexed is reported as 0 by Google today and null means the engine does not report. Those are exactly the caveats an agent needs to avoid misreporting 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 one-line purpose followed by labeled blocks (Use when / Not for / Returns / Cost / Example). Every line carries distinct information; no filler or restated 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?

Although an output schema exists, the description still summarizes rows[] fields and the null convention, and it covers cost, caching and routing. For a two-parameter read tool there is nothing material an agent needs that 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 both parameters (engine enum, property id format) are already fully documented in the schema. The description adds only a worked example for property and does not explain the engine/bing semantics further; 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?

The first sentence names a specific verb+resource (sitemaps submitted for a property) and enumerates the payload fields (read time, URL counts, errors). It is immediately distinguishable from console_submit_sitemap, console_inspect_url and seo_run_technical_crawl, which are also 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?

Provides explicit 'Use when' trigger phrases in the user's own vocabulary ('is my sitemap picked up', 'how many URLs did Google read') and a 'Not for' block that routes three adjacent needs to their correct siblings. Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent safety, but the description goes well beyond: it discloses the 2,000-inspections-per-property-per-day quota shared by all property users, the cost (0 credits, Google only), the 24-hour cache, and the meaning of null values. These are operational constraints an agent cannot infer from 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?

Front-loaded purpose sentence followed by clearly labeled Use when / Not for / Returns / Cost / Example blocks. Despite being information-dense, every line carries decision-relevant content and nothing repeats the schema or annotations.

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 names the key return fields and their null semantics, adds quota, cost and caching behavior, and shows a valid call. Nothing an agent needs to select or correctly invoke this 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?

Schema coverage is 100% and already documents both parameters, so the baseline is 3. The description adds the scoping relationship ('one URL of the user's property') and a concrete example object showing the sc-domain property id paired with a URL, which reinforces format expectations beyond the schema text.

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 ('Google's index status for one URL of the user's property') and enumerates the concrete payload (index status, last crawl, canonical, mobile usability, rich results). An agent can immediately distinguish this single-URL inspection tool from siblings like console_get_search_analytics or seo_get_page.

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?

Explicit 'Use when' triggers are given as concrete user phrasings ('why is this page not in Google', 'which canonical did Google pick') and the 'Not for' section routes bulk-URL needs to console_get_search_analytics with dimension page, HTML inspection to seo_get_page, and Bing elsewhere. Both inclusion and exclusion conditions are stated, plus a follow-up-fix checking scenario.

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, idempotent, non-destructive), and the description layers on non-obvious operational facts: 0 credit cost, 60 calls/minute per workspace, 1-hour cache. It also discloses a non-obvious response sentinel, NotConnected, plus the connect_url the user needs to fix it — behavior an agent cannot get from 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?

Front-loaded summary followed by labeled Use when / Not for / Returns / Cost / Example sections, each earning its place. The Returns detail is somewhat long given an output schema exists, but it carries the NotConnected and property-id-format information that is genuinely useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-optional-param, read-only listing tool, the description covers purpose, routing, cost, rate limits, caching, and the disconnected-account edge case. Even with an output schema present, the NotConnected guidance is essential to calling it correctly in a chain.

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% and the enum is self-documenting, so baseline is 3. The description adds an explicit example call ({"engine": "all"}) and clarifies that the property value returned is the id to pass onward, including its concrete formats, which helps the agent understand what the parameter selection yields downstream.

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 resource (Search Console and Bing Webmaster properties readable by the workspace's connected accounts) and its role as the entry point ('the first console call; every other console tool takes a property from here'). This cleanly separates it from console_get_* siblings, which need a property id.

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?

Explicit 'Use when' triggers (what sites are in my Search Console, before any console_get_* call, checking which engine is connected) and explicit 'Not for' routing to seo_get_domain_overview for third-party sites and seo_get_serp for live rankings. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the description's 'A write to the user's own account' is consistent rather than revelatory. It does add real context beyond the annotations — zero credit cost, never cached, a read-only connection returning NotConnected, and expected engine latency with console_get_sitemaps as the follow-up check. The 'resubmitting says it changed' note is behaviorally useful but overlaps with idempotentHint, so this is solid but not exceptional.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) make it scannable rather than a prose wall, and the core action is stated in the very first sentence. Every line carries information an agent would otherwise have to guess, with no restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with an output schema, the description covers everything an agent needs before calling: cost (0 credits), caching behavior, auth prerequisite (write-capable connection, else NotConnected), the shape of the returned record, and how to verify the result later. 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 description coverage is 100%, so all three parameters — including the google/bing enum and property id formats — are already fully documented in the schema, which sets the baseline at 3. The description corroborates the property scoping ('one of the user's properties') and supplies a concrete example payload, but adds no new semantics such as sitemap index constraints or per-engine property-format rules beyond what 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 first sentence gives a specific verb and resource ('Submits or resubmits a sitemap for one of the user's properties') plus the effect ('asking Google or Bing to read it again'), and the 'Not for' block names the sibling tools it is not (console_submit_urls, console_inspect_url). An agent can distinguish it from every other console_* tool 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?

Explicit when-to-use triggers are given in the user's own words ('get my new pages indexed', 'I just published', after a migration), and explicit exclusions route to alternatives: per-URL Bing submission goes to console_submit_urls, index status goes to console_inspect_url. It even closes the closest gap by explaining Google has no single-URL indexing API, so the sitemap is the only path.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses quota mechanics (per-site daily quota, starting near 10 URLs/day for new sites), cost (0 credits, never cached), account scope (write to the user's own account), and partial-failure behavior (InvalidTarget for out-of-site URLs, ProviderUnavailable for over-quota URLs that are not sent). This is the kind of 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?

Front-loaded with the one-sentence purpose, then labeled Use when / Not for / Returns / Cost / Example blocks that an agent can scan quickly. The Returns block substantially restates the output schema, which is the one section that does not fully earn its space, though the quota sub-fields do add orientation.

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 write tool with quota constraints and partial-failure modes, everything an agent needs is present: when to call it, what it costs, what the quota ceiling means, what errors come back and why. The output schema exists, so the Returns section is bonus rather than a gap, and no prerequisite (site must exist in console_list_properties) is left implicit.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value with a concrete example payload showing that property is the site root URL and urls is an array of full page URLs, plus the per-call quota ceiling that governs how many URLs are actually accepted. It does not add detail beyond the schema on the 2048-char or 500-item limits, which are already documented.

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?

"Asks Bing to crawl specific URLs of the user's site now, within Bing's daily quota" states a specific verb (submit/request crawl), resource (individual URLs), engine (Bing) and scope (per-site quota). It is immediately distinguishable from console_submit_sitemap, which handles whole-site submission.

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?

Explicit "Use when" triggers (just-published post, uncrawled page, page needing recrawl) and an explicit "Not for" block that routes Google to console_submit_sitemap with engine google and failed crawls to console_get_crawl_issues first. Both inclusion and exclusion conditions are named with the exact sibling to use 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 cover read-only, idempotent, non-destructive, open-world, but the description adds value they cannot: text is truncated at 2000 characters, replies carry parent_id/depth, cost is 1 credit per page, and results are cached for 6 hours. Those are exactly the operational facts an agent needs before spending credits or trusting truncated output.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) with the core statement front-loaded in one sentence. Every line carries distinct information; 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?

For a 4-parameter, paginated read tool with an output schema and full annotation coverage, the definition supplies scope, exclusions, return shape, cost, caching, and an example. An agent has everything required 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 description coverage is 100%, so url, cursor, dry_run, and max_credits are already documented. The description adds only a concrete example URL (a reel), which mildly clarifies accepted input forms, but it never explains cursor paging or how dry_run/max_credits interact with the stated per-page cost. Baseline 3 is appropriate when the schema does the heavy lifting.

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 precise verb+resource+scope: "The comments on one Facebook post." It is immediately distinguishable from facebook_get_post (the post itself), facebook_get_posts (many posts), and facebook_get_group_posts 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?

Explicit "Use when" for page/group post replies, plus a "Not for" section that names the sibling to use instead (facebook_get_post) and states the unsupported case (comments across many posts, which Facebook does not offer). Nothing is left to inference.

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

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

Goes well beyond the annotations (readOnly, idempotent, openWorld, non-destructive) by disclosing cost (1 credit per page), a 6-hour cache window, text truncation at 2000 characters, the null/empty convention meaning 'not published', and the fact that a complete window is not available so the caller must page and dedupe. Those are exactly the operational facts an agent needs before spending 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-loaded with purpose and usage, then structured into labeled Use when / Not for / Returns / Cost / Example blocks that are easy to scan. The Returns paragraph is a long unpunctuated enumeration that sprawls a bit and partly repeats the output schema, but almost every element is functional.

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 paginated, credit-metered scraping tool with five optional parameters, the description covers ordering, paging, dedupe, cost, caching, truncation, and null semantics. Return-field documentation is technically redundant given the output schema, but it does not leave the agent short of anything needed to call 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 parameter descriptions already carry the syntax; the description adds contextual meaning on top, tying the credit cost to max_credits/dry_run and reinforcing the url argument ("Give the group's url") plus cursor-based paging. It omits any mention of the `handle` parameter, which is left entirely to 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 posts in one Facebook group, newest first" gives a specific verb (fetch), a precise resource (group posts, not page posts), and an ordering guarantee. The 'Not for' line explicitly separates it from facebook_get_posts, which is the only sibling it could be confused 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?

Includes an explicit 'Use when' scenario (community monitoring, with the reddit_get_new_posts analogue), an explicit 'Not for' exclusion naming facebook_get_posts as the alternative, and practical guidance to page with the cursor and dedupe on id.

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/idempotent/openWorld annotations, it discloses cost (1 credit), 6-hour caching, text truncation at 2000 characters, and the meaning of null/empty results. The field-by-field return listing overlaps with the existing output schema, so a point is withheld for that redundancy.

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?

Labeled sections (Use when / Not for / Returns / Cost / Example) front-load the decision-relevant information before the field list. The long enumeration of returned fields is the one segment that does not fully earn its space given 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?

A read-only single-item lookup with rich annotations and an output schema needs nothing more: cost, caching, truncation, null semantics and routing to siblings are all covered. An agent can invoke this correctly and interpret edge cases without further information.

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 value with a concrete example showing that a reel URL is an acceptable `url` value. The `dry_run` and `max_credits` parameters are left entirely to the schema, which already explains them adequately.

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 and immediately scopes the payload ("One Facebook post with its reactions, comments, shares and views"), which cleanly separates it from facebook_get_posts (list) and facebook_get_comments.

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?

Explicit 'Use when' (a single row is worth the detail, or you only have a URL) and 'Not for' clauses that name the exact sibling to use instead for comments and for video speech. The selection logic is fully spelled out with no inference required.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the bar is lower. The description still adds substantial operational context the annotations cannot: 1 credit per page, 6-hour cache, text truncated at 2000 characters, null/empty meaning 'platform does not publish it', and that shares is always null on Facebook. Pagination is only implied by the cursor parameter in the schema rather than described here.

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?

Labelled sections (Use when / Not for / Returns / Cost / Example) make it scannable and the scoping rule is front-loaded. The Returns block is comparatively long and partly overlaps the existing output schema, so a few lines could be trimmed without loss.

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 paginated, credit-metered social read endpoint with zero required parameters, the description covers selection, alternatives, cost, caching, truncation, and null semantics. Combined with the output schema and annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so a baseline of 3 would be acceptable, but the description adds the mutual-exclusivity rule 'give one of handle or url' that the schema does not encode (both are optional, neither required). It also gives cost semantics for the credit-related parameters and a concrete url example, though it does not explain cursor or max_credits behavior directly.

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: posts from a single Facebook page, ordered newest first. The 'Not for' sentence explicitly distinguishes it from facebook_get_group_posts and facebook_get_post, so an agent can route 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?

Provides an explicit use case (watching what a business page publishes, judging cadence and reactions) plus two named alternatives with the conditions that select them. Nothing about when to choose this tool is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive and open-world, but the description adds materially more: a 1-credit cost, a 24-hour cache, and the meaning of null/empty values (the platform does not publish the field). It also clarifies that running_ads and ad_library_id interoperate with ads_get_advertiser_ads, 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?

Front-loaded with the core statement, then organized into labeled Use when / Not for / Returns / Cost / Example blocks. The Returns sentence is dense but every clause (including the null semantics and the kind=company note) 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?

Despite an existing output schema, the definition still tells the agent what a null means, what the credit cost and cache window are, and which sibling handles the excluded cases. For a 4-parameter lookup tool, 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 baseline is 3; the description goes beyond it by stating the selection constraint "Give one of handle (a page name) or url", which the schema does not express as a oneOf, and by glossing handle as a page name rather than a person. A worked example URL further anchors the url format.

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 and resource ("One Facebook page") and immediately enumerates the data it covers: followers, category, address, website. It is clearly distinguishable from facebook_get_posts and ads_get_advertiser_ads, both of which are 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?

Explicit "Use when" and "Not for" sections route the agent to the right sibling: posts go to facebook_get_posts, ads go to ads_get_advertiser_ads with platform facebook. Both the affirmative condition and the exclusions are stated, leaving nothing 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, idempotency, non-destructiveness and open-world access, so the description focuses on what they cannot express: cost (1 credit), 30-day caching, the returned record shape, and the NoData outcome when a post has no speech. That is solid added context. The only small gap is that it doesn't mention what happens on an uncached or unsupported URL beyond the implicit NoData case.

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 one-line definition followed by labelled Use when / Not for / Returns / Cost / Example blocks. Every line carries information an agent would otherwise have to guess, and there is no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-explained, yet the description still names the key fields and the empty-result case. With all four parameters documented at 100% coverage and cost/caching disclosed, an agent has everything needed to call this 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 the baseline is 3 and the schema already documents url, dry_run, language and max_credits. The description adds one concrete thing the schema lacks: a worked example showing a real reel URL shape, which clarifies the expected input format. It says nothing about the transcript language preference or budget guard, but those are fully covered by schema text.

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 — 'What is said out loud in one Facebook video or reel, as text' — and immediately scopes it to a single object ('one'). It explicitly contrasts with facebook_get_post ('Not for: the post's text'), so an agent can distinguish it from the nearest sibling 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?

Provides an explicit 'Use when' clause (reading a video without watching it, extracting claims from an ad or clip) and an explicit 'Not for' exclusion that names the correct alternative tool. Both the positive and negative routing conditions are given, leaving nothing to inference.

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