Manifold MCP

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

Beyond the annotations (readOnly/idempotent/openWorld), it discloses cost (1 credit, 7-day cache), data-quality quirks (impressions/spend are published ranges so returned as text), platform coverage limits (reach/payers only for facebook ads in EU/UK), and a google-specific null fallback for first_shown with a cross-reference to where the value lives instead.

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 scoping, then clearly labeled Use when / Not for / Returns / Cost / Example sections. The Returns section is long and partly duplicates the output schema, but almost every clause carries platform-specific caveats that earn their place.

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

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

For a 4-param, output-schema-backed read tool, the definition covers routing, cost, caching, per-platform field availability and edge cases, leaving nothing an agent needs to call it correctly unstated.

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 an example call but says nothing about dry_run, max_credits, or the per-platform meaning of id beyond what the schema already documents, so it does not materially enrich parameter usage.

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 retrieval verb and resource ('One ad from a platform's public library') plus what the ad record contains (creative text, destination, targeting). It is immediately distinguishable from the sibling listing tools absent from its 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?

It gives an explicit 'Use when' (reading the offer/CTA behind an ad found in a list) and a 'Not for' that routes set-level queries to ads_search_ads or ads_get_advertiser_ads and video content to the platform's transcript tool. Both the condition and the alternatives are 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 cover safety (readOnly, idempotent, openWorld, non-destructive), but the description adds genuinely new operational context: cost (1 credit per page, 25 on google with details), a 24-hour cache, and the caveat that impressions/spend are published ranges returned as text. That is substantive behavioral disclosure beyond structured fields.

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

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

Front-loaded with the core purpose, then labeled sections (Use when / Not for / Returns / Cost / Example) that scan cleanly. Every sentence carries distinct information — no filler or restatement of the name.

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

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

Despite 8 parameters and a rich return list, the description covers routing, cost, caching, an example call, and notes on the ambiguous impressions/spend fields. With an output schema present, it does not need to detail every field, yet it still summarizes the row shape usefully.

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 earns extra credit by giving a concrete invocation example ({"platform": "google", "advertiser": "lululemon.com"}) that shows how the loosely-typed platform/advertiser pair is actually supplied. The cost line only restates what the schema already says about the details flag.

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 ad one advertiser is running, from a platform's public library') and immediately scopes it against siblings by naming both ads_search_ads and ads_get_ad. An agent can distinguish this tool from the other ads_* tools 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' (competitor teardown) and 'Not for' clauses with named alternatives and the condition that selects each ('a keyword sweep across advertisers, use ads_search_ads. One creative in full, use ads_get_ad'). This is textbook when/when-not/alternative routing.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, idempotent, openWorld), and the description goes further with credit cost per page, 24-hour caching, and the caveat that impressions/spend are published text ranges rather than numbers. The Returns enumeration largely restates what the output schema already carries, which slightly dilutes the added value.

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 with labeled sections (Use when / Not for / Returns / Cost / Example) and no wasted prose. The Returns block enumerates fields already present in the output schema, so it is slightly longer than necessary.

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

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

For a 7-parameter, open-world search tool with an output schema, the description covers routing, cost, caching, and data-format quirks, leaving no gap an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete usage example and reinforces what 'query' accepts (keyword, product or brand), giving marginal but real semantic help 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 ('Ads running on a platform's public library, by keyword or brand') and immediately distinguishes itself from ads_get_advertiser_ads and ads_search_advertisers. An agent can tell exactly what this returns versus its siblings.

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' scenarios ('what ads is this category running', competitor angles/offers) and 'Not for' exclusions naming the correct alternatives, including the Google-specific routing via ads_search_advertisers and organic posts via the platform's own search. 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 establish read-only, idempotent, open-world, non-destructive behavior, so the baseline is covered. The description adds genuinely useful operational context beyond that: 1-credit cost, 7-day caching, and the one-entry-per-region semantics that explain why results are region-scoped. It does not discuss auth or failure modes, keeping it just short of full marks.

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-line purpose, then labeled Use when / Not for / Returns / Cost / Example blocks. Every sentence carries routing, cost, or format information; nothing is filler or restated boilerplate.

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

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

Despite an output schema existing, the description lists the returned row shape, which costs little and aids downstream chaining, and it covers routing, cost, and caching. An agent has everything needed to call this correctly and to know what to do with the result.

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 every parameter. The description adds the reason region matters (one brand has one entry per region) and a concrete example call showing the platform/query/region combination, which clarifies usage beyond the raw field docs.

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 ('advertisers matching a brand name in Google's ad library, with their ids') and immediately distinguishes itself from the two closest siblings. An agent can tell it apart from ads_get_advertiser_ads and ads_search_ads 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' clause routes the agent here before ads_get_advertiser_ads because that library is keyed by id. Explicit 'Not for' clause redirects to ads_get_advertiser_ads for the ads themselves and to ads_search_ads for other libraries. Both the trigger and the exclusions are 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 readOnly/openWorld/idempotent/non-destructive, and the description layers substantial extra context on top: cost (0 credits), rate limiting, 1-hour caching, the ~17-fetch mechanism, and explicitly 'No crawl, no LLM call'. This is well beyond what the annotations convey.

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

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

Well front-loaded: purpose first, then use/not-for routing, then returns. However, the lengthy 'Returns:' block is partly redundant since an output schema exists, making the definition larger than strictly necessary.

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

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

For a complex multi-fetch tool, the description covers mechanism, cost, caching, failure semantics (tier meanings, checks that never fail on absence) and boundaries. Combined with the existing output schema, 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% for the single 'target' parameter, and the schema already explains 'A domain or URL. Every fetch goes to its origin.' The description's example ({"target": "example.com"}) adds only marginal clarification, so the baseline of 3 applies.

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

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

The description states a specific verb+resource ('whether a site is set up for AI answer engines') and enumerates exactly what it examines (robots.txt per AI crawler, WAF/CDN blocks, raw-HTML content, noindex, llms.txt, etc.). It clearly separates itself from siblings by naming aeo_run_ai_answers, seo_run_technical_crawl and seo_get_page. An agent can identify this tool without opening the schema.

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

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

Explicit 'Use when:' triggers are given ('do we block GPTBot', 'are we blocking ChatGPT at Cloudflare', before an AI visibility push) and an explicit 'Not for:' list routes to the correct alternatives (aeo_run_ai_answers, seo_run_technical_crawl, seo_get_page). Both when-to-use and when-not-to-use are covered.

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

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

Annotations declare it non-readOnly and non-idempotent but say nothing about async behavior or cost. The description adds the crucial asynchronous pattern (returns task_id, read via get_task), the per-engine credit costs, the 30-day retention/no-cache policy, non-determinism of answers, engine-specific data quirks, and that failed cells are not charged. This is rich context beyond the annotations.

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

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

Front-loaded with the core purpose, then a sequential 'Slow / Use when / Not for / Returns / Cost / Example' structure that is easy to scan. It is long, but nearly every sentence carries actionable information (cost table, data-availability caveats), so waste is minimal.

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, credit-metered tool with an output schema, the description covers invocation mechanics, return shape, engine-specific semantics, cost, and failure handling. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it explains per-engine cost differences tied to the 'engines' parameter, the credits/estimate behavior relevant to max_credits/dry_run, and gives a worked example with prompts and brands. It adds meaning on top of the schema rather than repeating it.

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 output ('what AI engines answer for a prompt, with brands mentioned and sources cited') with a clear verb/resource framing. It distinguishes itself from siblings by naming aeo_search_prompts, seo_get_serp, and aeo_get_site_readiness as the tools for adjacent jobs. An agent can select it without opening another 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:' scenarios (e.g. 'does ChatGPT recommend us for X', AI visibility baseline) and a 'Not for:' block that routes each adjacent case to the correct alternative tool. The when/when-not/alternatives triad is fully covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial context they cannot: the exact cost formula (31 + 31 per 100 rows, 47 credits at default), 7-day caching, dry_run costing nothing, and semantic caveats such as ai_search_volume being a People Also Ask proxy rather than query logs.

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

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

Front-loads purpose in sentence one, then routes usage, then returns, cost, and a concrete example. Every block serves a decision the agent must make; 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 nine-parameter tool with no required fields, the description supplies everything the schema lacks: exclusivity constraint, cost/budget behavior, caching, engine scope, and the practical example call. Return-field semantics add value even though an output schema exists.

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 the baseline is 3, but the description adds a cross-parameter constraint the schema does not encode ('Give exactly one of keyword or domain') plus meaning for domain vs keyword inputs in the mentions_brand definition. It does not add further per-parameter detail, so it lands just above baseline.

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

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

States a specific verb and resource ('prompts people ask an AI engine... about a topic or brand') and explicitly disambiguates from keywords ('Not keywords'), which matters given the large family of *_search_keywords siblings. An agent can distinguish this from seo_search_keywords and aeo_run_ai_answers immediately.

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

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

Provides explicit 'Use when' scenarios in user-question form and a 'Not for' clause naming both alternatives (seo_search_keywords for Google keywords/volumes, aeo_run_ai_answers for current engine answers) with the selecting condition. It also states the keyword/domain exclusivity rule.

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/non-destructive/openWorld) by disclosing the credit cost model (5 + 5 per 100 rows), the 7-day cache, and that the queried product itself is excluded from results. It also notes ASINs-only payloads and points to amazon_get_product for titles.

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 and broken into Use when / Not for / Returns / Cost / Example sections, each earning its place. The Returns field list is somewhat redundant given an output schema exists, which slightly inflates 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?

For a read-only, cost-bearing query tool, the description covers routing, output shape, cost, caching, and the one caveat (the product itself is excluded). An agent has everything needed to call it correctly without extra exploration.

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 incremental value by tying limit to cost ('Default 100 rows = 10 credits') and giving a concrete call example. It does not add meaning beyond the schema for cursor, max_credits, language, or location.

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

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

States a specific verb+resource: products that compete with one product for the same searches, plus the shared-keyword/ranking dimensions. It explicitly distinguishes itself from amazon_search_products (one search's results) and seo_get_serp_competitors (web), so an agent can route without opening schemas.

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

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

Provides explicit 'Use when' triggers ('which products compete with ours', 'who shows up beside this ASIN') and an explicit 'Not for' clause naming the correct alternatives for both search-result and web-competitor cases. 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 readOnly/openWorld/idempotent/non-destructive, so the safety bar is covered; the description goes further with the credit cost formula (5 + 5 per 100, with a worked example), a 7-day cache window, and the null-means-no-data return semantic. These are exactly the operational traits an agent cannot get from annotations.

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

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

Front-loaded one-line summary, then labeled blocks (Use when / Not for / Returns / Cost / Example) with no filler. Every sentence carries a distinct fact and the alternative-tool routing appears before the logistics.

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 5 parameters, an output schema present, and annotations covering safety, the description supplies everything else an agent needs: cost model, caching, volume semantics, input ordering, and a call example. Nothing required 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 80% and already documents dry_run, language, location and max_credits, so the baseline is 3. The description adds meaning the schema lacks: the 1,000-keyword cap and the order-preservation behavior for the keywords array, plus a concrete JSON example. It does not discuss the budget/dry-run interaction, 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?

States a specific verb and resource (monthly Amazon search volume for keywords) plus hard scope boundaries: up to 1,000 keywords, input order preserved, only keywords you already have. This clearly separates it from amazon_search_keywords (discovery) and seo_get_keyword_metrics (Google).

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 give three concrete scenarios, and 'Not for' names the exact alternative tool for each wrong-intent case (seo_get_keyword_metrics for Google volume, amazon_search_keywords for keyword discovery). An agent needs no inference to route correctly.

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), and the description adds information annotations cannot carry: credit cost formula (5 + 5 per 100 rows, default 10), 7-day cache behavior, and sort order of results. This is exactly the extra behavioral context the bar asks for.

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

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

Purpose is front-loaded in one sentence, then cleanly partitioned into Use when / Not for / Returns / Cost / Example. Every line is actionable and none is redundant with 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?

Output schema exists, yet the description still summarizes the row shape and sort order, plus cost, caching, and pagination-relevant params. For a 7-parameter, cost-bearing tool this leaves no meaningful gap 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 description coverage is 100%, so the baseline is 3; the description earns above baseline by supplying a concrete invocation example ({"asin": "B0B41YH9B6", "limit": 50}) and by tying 'limit' to its cost consequence ('Default 100 rows = 10 credits'). It stops short of explaining cursor or dry_run semantics beyond what the schema 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?

The opening sentence names a specific verb+resource (searches a product ranks for) and enumerates the returned fields: volume, position, organic vs sponsored. It is immediately distinguishable from siblings like amazon_search_keywords (keyword discovery) and seo_get_ranked_keywords (Google).

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 with natural-language user phrasings, and a 'Not for' block routes to two named alternatives with the exact 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: cost (2 credits), cache duration (1 day), and the limitation that customer reviews are not available for Amazon. It does not cover auth or error behavior, but with annotations the bar is lower and this is useful added context.

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

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

The description is front-loaded with purpose and usage, then returns, cost, and an example. It is well structured, though the detailed 'Returns' list somewhat duplicates the existing output schema, which slightly reduces conciseness.

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 rich input schema, existing output schema, and annotations, the description is complete: it covers purpose, usage, alternatives, cost, caching, and return-field summary. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds only an example ASIN and does not provide additional syntax or format meaning beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource: retrieve one Amazon product by ASIN, and lists the main fields returned. It explicitly distinguishes itself from siblings by naming amazon_get_sellers and amazon_get_keywords for different needs, so an agent can route correctly.

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' examples and a 'Not for' section that routes to alternative tools. This gives clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds genuinely new behavioral context: 2-credit cost, 6-hour cache, and the semantic gotcha that has_featured_offer can be false (no Buy Box) with rows starting at rank 2, plus seller_url being null for Amazon itself. This is more than the annotations provide.

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

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

Front-loaded with the core purpose, then clearly partitioned into Use when / Not for / Returns / Cost / Example blocks. Dense but every line carries actionable information with no filler.

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

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

Although an output schema exists, the definition still disambiguates the tricky return fields (rank 1 = Buy Box, nullable seller_url, has_featured_offer=false edge case), and covers cost, caching, and routing. 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 description coverage is 100%, so the schema already documents asin, dry_run, language, location, and max_credits, making 3 the baseline. The description contributes only a single example call ({'asin': 'B0B41YH9B6'}) and says nothing about the dry_run/max_credits budget mechanics 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?

Opens with a specific verb+resource and scope: 'Every seller offering one Amazon product', then enumerates the returned data (price, condition, shipping, delivery, Buy Box). It is immediately distinguishable from amazon_get_product (the listing) and shopping_get_sellers (other stores), both of which it names.

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 ('who sells this ASIN', 'are resellers undercutting our price') and an explicit 'Not for' clause routing to sibling tools amazon_get_product and shopping_get_sellers. Nothing about tool selection 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds material context the annotations do not: a priced cost model (5 + 5 per 100 rows), the 7-day cache window, and the returned row shape. These are exactly the billing/caching traits 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?

Labeled sections (Use when / Not for / Returns / Cost / Example) make it skimmable and front-loaded with the core purpose. Slightly denser than necessary for a 7-param tool but every line carries actionable information, so little is wasted.

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

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

For a paginated, paid, cached search tool this covers everything an agent needs: scope, alternatives, return fields, pricing, cache lifetime, and a call example. An output schema exists, so return values do not need further elaboration.

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, but the description adds real value beyond it: it ties 'limit' to cost ('default 100 rows = 10 credits') and supplies a worked example invocation. It does not explain cursor pagination or the dry_run/max_credits interaction 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+resource (Amazon search ideas around a seed, sourced from Amazon related searches, with monthly volume) and explicitly excludes the two nearest siblings by name, so an agent can distinguish it from seo_search_keywords and amazon_get_keyword_metrics 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 an explicit 'Use when' with two concrete trigger scenarios and a 'Not for' section that routes to seo_search_keywords for Google data and amazon_get_keyword_metrics for volume on known keywords. When-to-use and when-not-to-use are both covered with named alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive, so the safety profile is covered; the description goes further by disclosing the cost model (2 credits per 100 results, default 100 = 2 credits) and the 1-day cache, which materially affects invocation strategy.

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, then labeled sections (Use when / Not for / Returns / Cost / Example). Every line carries information an agent needs; 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?

Output schema exists so return-value detail is optional, yet the description still summarizes the return shape and flags that related_searches can be empty. For a 6-param tool with cost and caching implications, nothing an agent needs 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 83%, so the baseline is 3, but the description adds the billing relationship for depth ('2 credits per 100 results. Default 100 = 2 credits') and a concrete example payload {'keyword': 'standing desk', 'depth': 100}. It does not clarify dry_run or max_credits, which the schema already documents.

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

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

States a specific verb+resource (search Amazon results page) and enumerates exactly what is returned (organic and sponsored products in order, with price, rating, reviews, bought-past-month, badges). An agent can distinguish it immediately from amazon_get_product and shopping_search_products.

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 ('who ranks on Amazon for standing desk') and a 'Not for' block that names the correct alternatives for adjacent tasks: amazon_get_product for a single listing, shopping_search_products for Google Shopping, amazon_get_keyword_metrics for volume. 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 cover read-only/idempotent/open-world safety, but the description goes further with cost (0 credits), caching (1 day), and result volume (several hundred rows, filter by custom or category) — operational traits no annotation conveys. It also discloses the exact row shape (kind, api_name, ui_name, category, custom, metric_type).

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 purpose and organized into Use when / Not for / Returns / Cost / Example sections, so it scans well. It is on the long side, but nearly every line carries actionable information rather than filler.

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

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

An output schema exists, yet the description still summarizes the return contract and pagination/volume considerations, plus cost and cache behavior for a read-only tool with a single required parameter. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a concrete call example ({"property": "properties/123456789", "limit": 1000}) and notes filtering by custom/category, giving practical invocation context 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 precise verb+resource (fetch every dimension and metric a GA4 property reports) and explicitly links the returned api_name to what analytics_get_report consumes. It is distinguishable from analytics_get_report and analytics_list_properties 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?

Explicit 'Use when' block enumerates concrete triggers (field outside the common ones, listing custom dimensions, checking a conversion/event-scoped field name, recovering from a rejected field). The 'Not for' clause names the alternative (analytics_get_report) and the condition that selects against it.

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

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

Annotations already establish this as a read-only, idempotent, non-destructive operation, but the description adds substantial behavioral context beyond them: return row shape, metric type meanings, currency/time zone handling, thresholding and (other) row caveats, rate scaling, settlement timing, zero credit cost, and one-hour caching.

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 long but tightly structured and front-loaded: purpose first, then use cases, exclusions, return semantics, constraints, cost, and an example. Each section earns its place by resolving a decision or invocation ambiguity for a complex reporting 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 an 11-parameter analytics report tool with nested filters, annotations, and an output schema, the description is complete enough to call correctly. It supplies alternatives, comparison-range coupling, cost/cache expectations, and result caveats without redundantly explaining the output schema.

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 input schema already carries detailed parameter semantics for filters, metrics, dimensions, dates, ordering, and pagination. The description adds useful meaning around comparison-range pairing and provides a concrete call example, though it leaves most individual parameters 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 description states a specific resource and scope: a GA4 report from the user's own property, with any metrics over any dimensions and an optional comparison range. It distinguishes itself from siblings by explicitly naming console_get_search_analytics for search queries and seo_get_traffic_estimates for sites the user does not own.

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 when-to-use examples such as traffic by channel, landing page conversion, revenue by source, and period-over-period comparisons. It also gives clear exclusions with alternatives, plus the constraint that compare_start_date and compare_end_date must be supplied together or not at all.

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/openWorld, and the description adds genuinely new behavior: a NotConnected failure mode with connect_url for reconnection, a cost of 0 credits, a shared 60 calls/min per-workspace rate limit, and a 1-hour cache. These are exactly the operational facts annotations cannot express.

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

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

Labeled sections (Use when / Not for / Returns / Cost / Example) make it scannable, and the core purpose leads. Length is justified by the routing and error information; no filler sentences.

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

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

Despite the empty input schema, the description covers invocation context, the connect_url error path, billing, rate limit, caching, and the shape of rows for chaining into analytics_get_*. Nothing an agent needs to call 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?

The tool takes zero parameters, so there is no parameter surface to document and the 0-param baseline of 4 applies. The description usefully clarifies the property id format ('properties/123456789') used downstream, but that is return-value context rather than parameter semantics.

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

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

States a specific verb (list) and resource (GA4 properties readable by the workspace's connected Google account) plus the account grouping. It distinguishes itself from console_list_properties and positions itself as the entry point for the analytics_* family, so an agent can tell it apart from siblings without opening schemas.

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

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

Explicit 'Use when' triggers ("what's in my Google Analytics", identifying which GA4 property is example.com) and a 'Not for' section that routes Search Console and unowned-site traffic to console_list_properties and seo_get_traffic_estimates respectively. It also states the dependency that other analytics tools take a property from here.

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, idempotentHint, openWorldHint, and non-destructive behavior, but the description adds substantial operational context beyond that: cost of 1 credit, 1-day caching, possible latency up to a minute, null semantics, and store-specific field quirks. These details help the agent set expectations and handle missing data correctly.

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

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

The description is front-loaded with the resource and its returned fields, then follows a predictable Use when / Not for / Returns / Cost / Example structure. Despite its length, every section adds actionable information for a complex, open-world tool, and there is no filler.

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

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

Even though an output schema exists, the description supplies critical context it cannot: per-store field differences, nullability rules, credit cost, caching, and latency expectations. Combined with the example and sibling routing, it gives the agent everything needed to call the tool correctly and interpret its 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 description coverage is 100%, so the schema already documents all six parameters, including the store enum and app_id format. The description only adds a concrete example invocation and does not explain dry_run, max_credits, language, or location beyond what the schema says, so the baseline of 3 applies.

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

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

The first sentence names the specific resource and enumerates the data returned (rating, installs, version, release notes, description, screenshots, developer contact), distinguishing this as an app store listing lookup. The 'Not for' section explicitly routes the agent away from apps_get_reviews, apps_get_keywords, apps_search_apps, and apps_get_top_charts, so the tool is clearly separable from its closest siblings.

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' triggers and a 'Not for' section that names the correct alternative tool for each adjacent need. Nothing is left to inference about when this tool is the right choice versus apps_get_reviews, apps_get_keywords, apps_search_apps, or apps_get_top_charts.

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 the safety profile, and the description still adds material behavior: credit cost formula and default (10 credits for 100 rows), 7-day caching, US/English-only coverage, and the fact that the queried app itself is excluded from results. These are non-obvious traits an agent cannot infer from annotations.

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

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

Front-loaded one-line summary followed by labeled When/Not for/Returns/Cost/Example sections. Every sentence carries unique information; nothing is repeated from 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?

Given an output schema exists, the description need not enumerate returns, yet it labels the key row fields and adds cost, caching, coverage limits, and exclusion rules. Nothing an agent needs for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a concrete invocation example and clarifies that returned identifiers are ids only, requiring apps_get_app to resolve a name. It stops short of explaining cursor paging or dry_run/max_credits interaction beyond the cost note.

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 and scope: apps competing for the same store searches, plus the metrics returned (shared searches, rank strength). It explicitly distinguishes itself from the nearest sibling (seo_get_serp_competitors) so an 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?

Provides an explicit 'Use when' block with three natural-language triggers and a 'Not for' block naming two alternatives (seo_get_serp_competitors for web competitors, apps_get_shared_keywords for shared keywords). When, when-not, and alternatives are all present.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely non-derivable traits: credit cost model (5 + 5 per 100 rows), 7-day cache, US/English-only coverage, Google Play vs App Store data-coverage differences, and NoData semantics. This is unusually rich behavioral context that annotations cannot express.

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

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

Front-loaded with the core definition, then clearly labeled Use when / Not for / Returns / Cost / Example blocks. Lengthy, but every block adds usable information; only the Returns prose overlaps with the existing output schema, which keeps it short of a 5.

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

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

For a 6-parameter, billed, read-only tool this covers everything an agent needs: purpose, alternatives, output shape, cost, caching, and geographic/store coverage caveats. Even though an output schema exists, the extra ranking/sort and NoData notes are additive rather than 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 description coverage is 100%, so the schema already documents store, app_id, limit, cursor, dry_run and max_credits; baseline 3 applies. The description restates the return row fields (keyword, volume, rank, results_count) and gives a call example, but adds little about the parameters themselves beyond what the schema provides.

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

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

States a specific verb+resource ('Store searches an app ranks for') with scope (which store, monthly volume, position) and explicitly names siblings it is not (seo_get_ranked_keywords, apps_get_shared_keywords). An agent can distinguish it from the crowded sibling list 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' examples ('what does competitor's app rank for', 'which store keywords bring installs') and an explicit 'Not for' section that routes the agent to the correct alternatives by name. 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 the safe/idempotent read profile, yet the description adds cost (1 credit per 100 reviews), 6-hour caching, up to a minute latency, and the semantic caveat that ratings_count appears on every star rating most without text, unlike rows[]. This is real context beyond structured fields.

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

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

Front-loaded with a one-line purpose, then labeled Use when / Not for / Returns / Cost / Example blocks. Dense but every sentence carries actionable information and the structure makes it scannable.

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-param, network-backed, credit-consuming tool, the definition covers selection, caveats, cost, timing, and return-shape notes (including the rows_available end-of-fetch semantics), leaving no obvious gap an agent would need before calling.

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 baseline is 3. The description adds cross-parameter meaning the schema lacks: sort ordering ('newest or most relevant first') and the tie between limit and cost ('Default 100 = 1 credit'), plus a filled-in example call.

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

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

States a specific verb+resource (fetch user reviews of one app) plus the ordering options and returned fields. Explicitly disambiguates from siblings, naming apps_get_app for the listing and shopping_get_reviews for physical products.

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 concrete user intents ("what do users complain about", "recent 1-star reviews") and a 'Not for' block routing to two named alternatives with the distinguishing condition.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description clears it by adding cost (5 + 5 per 100 rows), a 7-day cache, and a hard geo/language restriction (United States and English only). It does not mention rate limits or how the cursor pagination behaves across pages, but the disclosed economics and coverage limits are exactly the context an agent needs.

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 purpose, then labeled Use when / Not for / Returns / Cost / Example sections. Dense but every line carries decision-relevant information; 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?

Output schema exists so return shape needn't be spelled out, yet the description still summarizes rows[] briefly. Combined with annotations covering safety and the description covering cost, caching, geo limits, and a usage example, nothing needed to call 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?

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema cannot: the ranks[] array is ordered as the apps were given, and the worked example clarifies the app_ids format per store. It also ties cost to the limit parameter, which the schema does not.

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') with the scope constraint baked in, and explicitly separates itself from apps_get_keywords and apps_get_competitors. An agent can distinguish it from every sibling 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 labeled 'Use when' block with concrete example queries and a 'Not for' block naming the two alternative tools and the conditions that select them. Both the inclusion and exclusion criteria are explicit.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful operational context: cost (1 credit per 100 rows, default 100 rows = 1 credit), 1-day caching, and potential latency up to a minute.

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 and organized into clear sections: purpose, use cases, exclusions, return shape, cost, and example. Every sentence serves a distinct purpose with no wasted text.

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

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

With an output schema present, the description still helpfully summarizes returned fields and includes cost, latency, caching, usage guidance, and an example. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is high (88%), so the schema already documents most parameters, including chart enums, category IDs, limit bounds, and dry_run. The description adds only a small amount beyond the schema, such as the cost implication of the default 100-row limit and a full example request.

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

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

The description states a specific resource and scope: a store's top chart, with chart types and overall/category options, in chart order. It clearly distinguishes itself from siblings by naming apps_search_apps and apps_get_app as alternatives for different needs.

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 and a 'Not for' section name the correct alternatives for app search and single-app details. An agent can decide when to call this tool versus apps_search_apps or apps_get_app without opening either schema.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: exact cost (31 + 31 per 100 rows, 62 credits default), 7-day caching, and the critical disclosure that a title matches on ANY single word (so 'habit tracker' returns flight trackers). That last point goes beyond annotations, but the score is capped because it largely repeats the schema's own word-match wording.

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, then labeled sections (Use when / Not for / Returns / Cost / Example) that make it skimmable. It is long but every section carries decision-relevant content 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?

An output schema exists, yet the Returns section still clarifies the row shape and warns of 'the same gaps' as apps_get_app, and cost/caching/matching/sort semantics are all covered. Nothing an agent needs to call 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?

Schema description coverage is 100%, so baseline is 3. The description adds value above the schema by explaining the practical implication of the query parameter (word-broadening) and advising 'search one distinctive word, with category', plus tying limit to the cost model. It does not, however, add meaning for cursor, dry_run, or max_credits beyond the schema.

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

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

The opening sentence gives a specific verb (search), resource (apps), and scope (title-match against a store-wide index, full listing plus developer contact details). It explicitly distinguishes itself from siblings by naming apps_get_top_charts and apps_get_app, 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?

It has explicit 'Use when' examples and a 'Not for' section that names two alternatives (apps_get_top_charts for rankings/charts, apps_get_app for a single known app, noted as 'much cheaper'). The selection conditions are stated, not implied.

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

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds substantive operational context beyond them: 0-credit cost, Bing-only scope, a 6-hour cache, and the retention quirk that fixed issues stay listed for a few days. That retention detail materially affects how an agent should interpret results.

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

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

Front-loaded purpose sentence followed by clearly labelled Use when / Not for / Returns / Cost / Example blocks. Despite covering many facets, each sentence carries distinct information with no padding.

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

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

For a read-only, single-property lookup with an output schema, this is more than complete: issue-type enumeration, pagination awareness, cost, caching, and retention are all covered. An agent has everything needed to call it and interpret the response.

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 limit, cursor and property are already fully documented in the schema (including default 100, cap 1000, and the console_list_properties source). The description only adds a sample invocation, not syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

The definition names a specific verb and resource ('URLs Bing had trouble crawling on the user's property') and enumerates the problem classes it surfaces (HTTP errors, redirects, robots.txt blocks, DNS/timeouts). An agent can distinguish it from console_get_search_analytics, console_get_sitemaps and console_inspect_url 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 'Use when' triggers ('what is Bing failing to crawl', 'which of my pages 404') and an explicit 'Not for' clause that names the alternative for Google-side checks (console_inspect_url) and for a full crawl (seo_run_technical_crawl). 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 read-only/idempotent/non-destructive, and the description adds substantial extra context: Google's ~2-day lag and 16-month retention, Bing's differing row semantics, aggregation-induced total discrepancies, 0 credit cost, and 6-hour caching. These are behavioral traits no structured field 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-loads the purpose, then uses labeled blocks (Use when / Not for / Returns / Cost / Example) that an agent can scan quickly. Despite its length, each sentence carries distinct, actionable information.

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

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

For a 9-parameter analytics tool with an output schema, the definition is complete: it covers selection conditions, engine-specific caveats, freshness, cost, and a worked 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 description coverage is 100%, so the baseline is 3. The description explains output-oriented behaviors (Bing row limits, date handling, aggregation) rather than adding syntax or semantics for the parameters themselves beyond what the schema already documents.

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 and the exact metrics returned (clicks, impressions, CTR, average position) plus the supported grouping dimensions. It clearly differentiates itself from siblings by being scoped to the user's OWN verified Search Console/Bing property.

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' example questions and a 'Not for' block that routes to named alternatives (seo_get_ranked_keywords, seo_get_keyword_metrics, console_inspect_url) with 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?

Annotations already declare the safe read-only, idempotent profile, but the description adds context beyond them: cost (0 credits), a 10-minute cache, and the crucial 'null = the engine does not say' semantics and the 'Google reports 0 today' caveat. This tells the agent how to interpret ambiguous results, which annotations cannot.

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

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

Front-loads purpose, then uses labeled sections (Use when / Not for / Returns / Cost / Example) that let an agent scan to exactly the information it needs. Every sentence carries signal 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?

With an output schema present and rich annotations, the description still adds return-shape detail, cost, caching, and null-handling. A two-parameter read tool is fully specified for correct invocation and interpretation.

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

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

Schema coverage is 100%, so both properties and the engine enum are fully documented in the schema itself. The description adds a concrete example for 'property' but no syntax or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('The sitemaps submitted for one of the user's properties') plus the data dimension it returns (read time, URL counts, errors). It is immediately distinguishable from siblings like console_submit_sitemap and console_inspect_url.

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 ('is my sitemap picked up', 'how many URLs did Google read') and a 'Not for' section that names three alternatives with the condition that selects each (submitting → console_submit_sitemap, indexing → console_inspect_url, missing pages → seo_run_technical_crawl). 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 readOnly, idempotent, non-destructive and open-world, but the description adds traits those annotations cannot express: a hard quota (2,000 inspections per property per day, shared across the property), a 24-hour cache, zero credit cost, and Google-only availability. These directly shape when an agent should call it and how often.

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 with labeled sections (Use when / Not for / Returns / Cost / Example) that an agent can scan quickly, and no throat-clearing. The Returns block is long and enumerates every field even though an output schema exists, so it is somewhat redundant rather than wasted, keeping this just short of a 5.

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

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

Covers purpose, triggers, exclusions with alternatives, quota, caching, cost, example invocation, and null semantics for unreported fields. With annotations and an output schema also present, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, and the baseline would be 3. The description adds a concrete example call ('property': 'sc-domain:example.com', 'url': 'https://www.example.com/pricing') that demonstrates the expected pairing, a small but real increment over 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 (inspect) and resource (one URL in Search Console) plus the scope it covers: index status, last crawl, canonical, mobile usability, rich results. It explicitly separates itself from console_get_search_analytics (bulk page-level data) and seo_get_page (the page's own HTML), so an agent can disambiguate without opening schemas.

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

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

Provides explicit triggers ('why is this page not in Google', 'when was this page last crawled', 'which canonical did Google pick') and explicit exclusions ('Not for: many URLs at once', page HTML, Bing) with a named alternative for each exclusion. 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 readOnly/idempotent/non-destructive/openWorld, but the description adds substantial context beyond them: zero credit cost, a 60 calls/min per-workspace rate limit, 1-hour caching, and the NotConnected response state with its connect_url. That is exactly the kind of operational detail 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-loads the identity sentence, then uses labeled blocks (Use when / Not for / Returns / Cost / Example) that are easy to scan. Slightly long, and the Returns enumeration partly repeats what the output schema already provides, costing one point.

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-parameter read tool with a rich output schema, this covers everything an agent needs: routing rules, cost, rate limit, caching, the connect-flow error state, and the property-id format to pass downstream.

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 single parameter is an enum with a default, so the schema already fully documents 'engine'. The description adds only a usage example ({"engine": "all"}) and no syntax or defaulting nuance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('The Search Console and Bing Webmaster properties the workspace's connected accounts can read') and explicitly positions itself as 'The first console call; every other console tool takes a property from here,' which cleanly separates it from console_get_* siblings.

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

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

Gives an explicit 'Use when' trigger list plus a 'Not for' branch that routes to named alternatives (seo_get_domain_overview for unowned sites, seo_get_serp for live rankings). When/when-not/alternatives are all present.

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

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

Annotations declare the safety profile (write, idempotent, non-destructive, open-world), and the description adds context those annotations cannot: resubmitting the same sitemap is the signal that the sitemap changed (explaining the idempotentHint), cost is 0 credits, the result is never cached, and a read-only connection returns NotConnected so the user must reconnect to grant submit access. That last point is a concrete auth failure mode an agent needs.

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 action in the first sentence, then uses labeled sections (Use when / Not for / Returns / Cost / Example) so an agent can scan to the relevant part. Every line carries information; nothing is padded or repeated from the schema.

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

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

Covers the full decision surface for a write tool: timing expectations ('the engine reads it later, usually within hours'), where to verify the result (console_get_sitemaps), cost, caching, and the auth failure mode. The output schema exists, yet the description still names the returned fields briefly without duplicating schema detail.

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 structured fields already document engine, property, and sitemap_url, making 3 the baseline. The description lifts it by binding the parameters into a concrete call example and by clarifying the sitemap/sitemap-index distinction and that the URL must sit under the property. Useful but adjacent to what the schema 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 ('Submits or resubmits a sitemap for one of the user's properties') and immediately scopes it to asking Google or Bing to re-read it. Sibling disambiguation is explicit later (console_submit_urls, console_inspect_url), so an agent can separate this from the other console write tools 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' list with quoted user utterances ('get my new pages indexed', 'I just published') and an explicit 'Not for' clause routing URL-level submission to console_submit_urls and index-status checks to console_inspect_url. It even explains the workaround rationale: Google has no one-URL indexing API, so the sitemap is the way.

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 safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds quota behavior (daily and monthly remaining, returned per call), the fact that over-quota URLs are dropped with ProviderUnavailable and off-site URLs yield InvalidTarget, zero credit cost, no caching, and that Bing's quota starts around 10/day for a new site. This is meaningful operational context beyond structured fields.

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

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

Front-loaded purpose sentence, then clearly labeled Use when / Not for / Returns / Cost / Example blocks. Despite its length, each block carries distinct decision-relevant information with no filler.

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

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

For a write tool with quota semantics, the description covers when to use it, what happens on failure, cost, quota growth behavior, and even summarizes return fields despite an output schema existing. An agent has everything needed to call it correctly and interpret partial failures.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly further by framing the urls array against the live quota ('never more than today's quota') and giving a concrete example tying property format to console_list_properties, which helps an agent construct a valid call.

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 ('Asks Bing to crawl specific URLs of the user's site now') plus the governing constraint (Bing's daily quota). It explicitly separates itself from console_submit_sitemap (whole site) and console_get_crawl_issues, so an agent can route correctly without opening schemas.

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

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

Provides an explicit 'Use when' list with concrete triggers ('I just published this post', uncrawled page, recrawl a fixed page) and a 'Not for' list naming alternatives for each exclusion: Google → console_submit_sitemap with engine google; whole site → console_submit_sitemap; failed crawls → console_get_crawl_issues first.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-annotation context: 1 credit per page, 6-hour caching, and the fact that comment text is truncated at 2000 characters. That is substantive behavioral disclosure beyond structured fields.

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

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

Front-loaded with the core action, then cleanly labeled sections (Use when, Not for, Returns, Cost, Example). Every sentence adds routing, cost, or field-level information without padding.

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

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

Although an output schema exists, the description goes further by summarizing row fields and the 2000-character truncation, and it covers cost, caching, and pagination cursor source. For a low-complexity read tool with annotations, schema, and output schema, 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 description coverage is 100%, so url, cursor, dry_run, and max_credits are already documented in the schema. The description adds an example URL and return-row structure but no additional syntax or meaning for cursor, dry_run, or max_credits. 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?

The description states a specific verb and resource: 'The comments on one Facebook post.' It also names the sibling tool it is not (facebook_get_post) and the scope it cannot cover (comments across many posts), letting an agent distinguish it immediately from facebook_get_post, facebook_get_posts, and facebook_get_group_posts.

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: reading replies to a page or group post, not the post itself (route to facebook_get_post), and not cross-post aggregation because Facebook does not offer it. This is a complete routing rule with an alternative 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 cover read-only/idempotent/non-destructive safety, and the description adds substantial context beyond them: 1 credit per page, 6-hour caching, the fact that Facebook does not offer a complete window so the caller must page with the cursor and dedupe on id, and that text is truncated at 2000 characters. These are non-obvious operational traits an agent needs.

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 with labeled sections (Use when / Not for / Returns / Cost / Example) and every line earns its place except the Returns field enumeration, which substantially duplicates the output schema. Slightly dense but organized.

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 tool with rich annotations and an output schema, the description covers the remaining agent-critical gaps: cost, caching, pagination/dedupe contract, and null semantics. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value: it ties cursor to 'the cursor' from paging with dedupe on id, clarifies that null/empty means the platform does not publish a field, and supplies a concrete url example. It does not, however, mention dry_run or max_credits semantics.

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

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

States a specific verb and resource ('The posts in one Facebook group, newest first') and explicitly distinguishes itself from the sibling facebook_get_posts by scope (group vs. page's own posts). An agent can route correctly without reading 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' and 'Not for' clauses, names the alternative tool to use instead (facebook_get_posts), and anchors the use case with an analogy to reddit_get_new_posts. This is the gold standard for routing guidance.

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

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

Annotations cover readOnly/idempotent/non-destructive, and the description adds real context beyond them: 1-credit cost, 6-hour caching, text truncation at 2000 characters, and the null/empty 'platform does not publish it' behavior. This is meaningful operational disclosure.

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

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

Labeled sections (Use when, Not for, Returns, Cost, Example) make it scannable and front-loaded. Every sentence carries information; nothing is filler.

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

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

Output schema exists, yet the description still flags the return fields and edge cases (truncation, null/empty), and it covers cost and caching. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents url, dry_run, and max_credits. The description's only added value is a concrete example URL, which is marginal. Baseline 3 applies 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?

States a specific verb (get) and resource (a single Facebook post) plus its bundled data (reactions, comments, shares, views). Clearly distinguished from the plural facebook_get_posts and from facebook_get_comments/facebook_get_transcript.

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 row worth the detail, or a bare URL) and 'Not for' clauses that route the agent to facebook_get_comments for comments and facebook_get_transcript for video speech. 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 cover the safety profile (readOnly, idempotent, openWorld), but the description adds operational context the annotations cannot: cost of 1 credit per page, a 6-hour cache, 2000-character text truncation, and null semantics ('Facebook publishes no share count, so shares is null'). These are exactly the traits that change how an agent plans and interprets 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?

Front-loads the one-line purpose, then labels sections (Use when / Not for / Returns / Cost / Example) so a scanning agent finds each fact immediately; every sentence, including the null-semantics note, 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 clarifies field meaning and null conventions that the schema alone would not disambiguate. Combined with cost, caching, and alternative-tool routing, nothing needed to call or interpret this tool 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, and the schema documents all five parameters. The description adds a real constraint not in the schema ('give one of handle or url', despite required=0) plus an example payload, but leaves cursor, dry_run, and max_credits 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 ('posts on one Facebook page') plus ordering ('newest first'), and explicitly contrasts itself with 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 when' scenario (watching what a business page publishes, judging cadence and reactions) and a 'Not for' clause that names both alternatives with the exact 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/non-destructive, but the description adds material context they cannot: cost (1 credit), 24-hour caching, budget behavior via max_credits/BudgetExceeded, the dry_run=free mode, and the semantic null/empty = not published convention. It also clarifies 'kind is company' because these are pages, not people.

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 routing decision before detail, and the single-line example gives a concrete call shape. Dense but every sentence carries distinct information with no filler.

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

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

Despite an output schema existing, the description still supplies the operational facts an agent needs: cost, caching window, budget guard, input requirements, and a working example. Nothing required 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 a constraint the schema does not express: 'Give one of handle (a page name) or url,' resolving the ambiguity created by required=0. It also glosses handle usage that the schema does not fully convey, though dry_run/max_credits semantics are left largely 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+resource ('One Facebook page') and immediately scopes what it covers: followers, category, address, website. It explicitly distinguishes itself from siblings by naming facebook_get_posts for posts and ads_get_advertiser_ads for ads, so an agent can route correctly without opening another 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 explicit 'Use when' conditions (verifying a business page is real/current, reading category and contact details) and explicit 'Not for' exclusions that route to named alternatives (facebook_get_posts, ads_get_advertiser_ads with platform facebook). 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: cost (1 credit), 30-day caching, and the NoData outcome when a post carries no speech. These are exactly the non-obvious operational traits an agent needs.

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 definition, then labeled sections (Use when / Not for / Returns / Cost / Example). Every line is informative and there is no filler.

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

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

With an output schema present, the description needn't detail return shape, yet it still names the key fields and the empty-result case. Combined with cost, caching, and annotation coverage, 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 description coverage is 100%, so url, dry_run, language, and max_credits are already documented. The description adds only an example call with the url field; it does not clarify dry_run or max_credits interaction with the stated credit cost, so it stays at the schema-driven baseline.

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

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

States a specific resource and output ('what is said out loud in one Facebook video or reel, as text') rather than restating the name. It explicitly distinguishes itself from facebook_get_post, which returns post text instead of speech.

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/clip) and a 'Not for' clause that names the alternative sibling (facebook_get_post). The routing decision is fully determined without opening any schema.

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 declare readOnly/idempotent/non-destructive; the description adds the behaviors that actually matter here: a 25-second blocking hold while the task runs, TaskPending polling with no backoff, TaskFailed carrying a reason, and 0 credits cost. None of that is derivable 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?

Front-loaded purpose first, then labeled Use when / Not for / Returns / Cost / Example sections that are each one or two lines. Every line carries a distinct piece of information with no restatement of the tool 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?

An output schema exists, yet the description still supplies the operational facts an agent needs to drive the async lifecycle correctly (blocking window, polling, failure case). Combined with the single required param, 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 description coverage is 0%, so the description must carry the load, and it mostly does: it gives a concrete example value ({"task_id": "task_01J..."}) and states the provenance of the id. It does not mention the minLength 1 / maxLength 100 constraints declared in the schema, so it stops short of full compensation.

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

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

States a specific verb+resource ('The result of a run_* tool') and immediately distinguishes itself from the async producers, naming TaskPending as the alternate return. An agent can tell this apart from seo_run_technical_crawl or aeo_run_ai_answers 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?

Explicit 'Use when' (holding a task_id from seo_run_technical_crawl or aeo_run_ai_answers) and 'Not for: starting work; call the run_* tool first.' It also prescribes the follow-up action on TaskPending ('call get_task again at once, with no wait first'), which is genuine usage routing rather than context.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds operational context the annotations cannot: per-page credit cost, the 15-credit flat charge for include_replies that applies even with zero replies, and a 6-hour cache. It also discloses text truncation at 2000 characters and that replies are omitted unless requested.

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