x402serps

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is low. The description adds genuinely useful non-schema behavior: the payment protocol (x402), exact price ($0.10 USDC flat on Base or Solana), the required X-PAYMENT header, and trial exclusion. It does not describe latency, failure modes on unpaid calls, or result volume, which keeps it from a 5.

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

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

Two sentences, front-loaded with what is returned and followed by the payment constraint; every clause carries information with no filler. It is dense but readable, and the pricing detail is appropriately separated from the capability statement.

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

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

With no output schema, the description usefully sketches the report contents, and it covers the payment prerequisite that would otherwise cause a failed call. The gap is the undocumented gl parameter and the absence of any note on what a paid-but-invalid request returns, which matters for a metered tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies that keywords is a list of 1-10 terms and that brand may be a brand or domain, but the third parameter, gl, is never mentioned and its meaning (geo/locale) must be guessed from the abbreviation.

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 uses a specific verb ('report') and names concrete outputs: SERP rank, AI Overview, answer box, People Also Ask, knowledge graph presence, competitors, and a 0-100 score, explicitly scoped to 1-10 keywords. That makes it clearly distinct from sibling tools like seo_audit or competitor_report, though it never names or contrasts those siblings directly.

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

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

Usage context is implied (brand-visibility auditing) and two real gating conditions are stated: it is paid via x402 and not included in the free trial. However, there is no explicit guidance on when to choose this over seo_audit or competitor_report, nor any note about repeat calls being unnecessary despite idempotence.

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 readOnly, openWorld, idempotent and non-destructive, so the safety profile is done. The description earns real credit on top of that by disclosing the auth/payment model ($0.02 USDC on Base or Solana via X-PAYMENT, or a prepaid Bearer xs_ key) and by admitting the current implementation is extractive rather than generative — a quality caveat an agent should factor in. It omits rate limits, latency/typical runtime, and failure modes (e.g. insufficient credit), which are the remaining behavioral unknowns for a paid 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?

Effectively two sentences: the capability first, then the commercial/auth terms. Front-loading the deliverable ahead of the payment details is the right ordering, and nothing is padded. Slightly dense — the payment clause packs currency, chain, header name and an alternative auth scheme into one run-on sentence.

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

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

For a conceptually simple retrieval-plus-summarize tool with no output schema, the description should still pin down the return shape (it does: a short answer with numbered citations) and the access requirements (it does: x402 or Bearer key). What is missing is the precondition that a question is actually supplied — required is empty, so an agent could invoke with no q and no query, and nothing warns against that. Mostly complete, with one gap on invocation preconditions.

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 80%, so the baseline is 3 and the schema already documents n (2-6, default 4), gl, and freshness. The description adds no parameter meaning at all and never addresses the q/query alias duplication, which is the one genuinely ambiguous input an agent could get wrong. Adequate but no marginal value.

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

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

The description gives a concrete verb chain ("web search, read the top pages, and return a short answer with numbered citations") that clearly separates this tool from raw-retrieval siblings such as web_search, search_extract, and extract. It states the output artifact (a cited answer), so an agent can tell what it gets back without opening the schema. It stops short of naming which sibling to prefer in which situation, which keeps it out of the top tier.

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?

Appropriate usage is only implied: you have a question and want a synthesized, cited answer rather than raw results. The one hard constraint disclosed is commercial rather than conditional — it is paid and explicitly "Not in the free trial," which does help an agent avoid calling it in a free-tier context. There is no explicit when-not guidance or named alternative for long-form research (e.g. deep_research) or raw search.

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 readOnly, idempotent, openWorld and non-destructive behavior, so the bar is lower. The description adds genuinely new context that annotations cannot express: the x402 payment model, the $0.08 USDC on Base price, and the X-PAYMENT header requirement. It could go further on what happens when payment is missing or rejected, but the auth/cost disclosure is valuable.

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

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

Two short sentences, front-loaded with capability and cost, and no filler. Every clause carries information the agent needs to decide and pay.

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?

This is a paid, multi-parameter tool with no output schema and zero schema descriptions, so the description bears a heavy load. It covers the payment mechanics well but leaves num undefined and says nothing about the shape of the batch response or per-query failure behavior.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It maps loosely onto queries via "up to 25," but the num parameter (1-20) is never explained at all — an agent cannot tell whether it is results-per-query, concurrency, or something else. With two undocumented parameters, this is a real gap.

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

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

"Up to 25 Web searches in one call" gives a specific verb (searches) and resource (web) with a batch scope, which distinguishes it from the single-query web_search sibling. It stops short of an explicit sibling comparison, but an agent can infer the batch role from the 25-query cap.

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

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

Usage is implied rather than stated: "in one call" and the 25-query cap signal batch scenarios, but it never says when to prefer batch_search over web_search or how to split work between them. It also omits what to do if a payment cannot be supplied.

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 readOnly, idempotent, non-destructive and open-world behavior, so the bar is lower. The description adds genuinely non-obvious context: the call costs $0.30 USDC on Base or Solana via an X-PAYMENT header, or requires a prepaid key sent as a Bearer token, and fails outside the free trial. It does not mention rate limits or failure modes beyond the payment gate.

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

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

Front-loaded with purpose and output inventory, then payment mechanics in a short second sentence. The output enumeration is long but each item is a distinct capability the agent needs to judge relevance. No filler or repetition.

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

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

With no output schema, the description carries the return-value burden and does so by listing the report sections. Payment and auth paths are both spelled out, and required inputs are clear. Missing only sibling differentiation and any sense of result volume/latency.

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

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

Schema description coverage is 100%, so all three parameters (gl, domain, keywords) are already documented with examples and the 1-8 keyword range. The description restates the keyword bounds but adds no new semantic detail such as keyword format, matching behavior, or how gl affects results. 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 resource (a competitor report keyed to a domain plus 1-8 keywords) and enumerates the payload: rankings, ads/advertisers, SERP features, share of voice, competitors and their top pages, plus the domain's own top pages. That is far more specific than a name restatement. It stops short of distinguishing itself from the closest sibling, seo_audit, which an agent must infer.

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

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

Usage is implied by the input shape (one domain, 1-8 keywords, optional country) and the tool explicitly flags that it is not covered by the free trial, which is a real gating condition. However, there is no when-to-use versus when-not guidance and no named alternative such as seo_audit or web_search for a cheaper, narrower lookup.

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 read-only, open-world, idempotent, non-destructive profile, and the description adds materially more: the x402 payment flow ($0.002 USDC on Base or Solana via X-PAYMENT), the alternative prepaid credit key via Authorization: Bearer xs_..., and the fact that it is not in the free trial. The per-page pricing tied to the requested limit is an important cost behavior an agent must know before calling.

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

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

It is one dense sentence, front-loaded with the action, and every clause (scope, return format, price, payment mechanism, trial exclusion) carries information. The heavy em-dash packing makes it slightly harder to scan than a clean two-sentence split would be.

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

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

For a four-parameter, no-output-schema tool, the description covers scope, return type, cost, and authentication, which is what an agent needs to call it correctly. It omits operational edge cases such as robots.txt handling, deduplication, or partial-failure behavior during a crawl.

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 four parameters (url, limit, include, maxChars) are already documented, including the 1-50 range and the charge-on-limit caveat. The description only restates the pricing-per-limit point and adds no new meaning for include or maxChars, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('crawl a website') plus the traversal strategy ('breadth-first from a start URL on the same host') and the return format ('clean markdown for up to 50 pages'). That distinguishes it in practice from extract or map_site, but no sibling is named explicitly, so differentiation is left to inference.

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

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

Usage is implied by the scope statement (same-host, breadth-first, up to 50 pages) and by the pricing/access notes, but there is no explicit 'use this when... instead of extract/map_site' guidance or any stated exclusion beyond the free trial.

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

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

Beyond the read-only and open-world annotations, it discloses parallel page retrieval, the number of pages read, the cited-excerpt output, the exact $0.08 USDC price, supported networks, the X-PAYMENT requirement, and free-trial exclusion. These details provide substantial operational and cost transparency.

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

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

Four compact sentences front-load the core behavior and output, then cover payment and the optional answer mode. There is no filler or redundant restatement of the annotations.

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

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

The description covers the workflow, output, and commercial prerequisites despite the absence of an output schema, making it broadly usable. However, the sparse input schema leaves important invocation ambiguities, and the lack of sibling routing limits complete selection guidance.

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

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

With 0% schema description coverage, the description explicitly explains only answer and indirectly conveys n through the 3-8 page range. The distinction between q and query remains ambiguous, especially with no required parameters, and maxChars is not explained.

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 specifies a concrete workflow and deliverable: search the web, read 3-8 top pages in parallel, and return a cited brief with excerpts. It does not explicitly distinguish this from siblings such as web_search, search_extract, or answer.

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

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

The description gives conditional guidance to set answer: true for an LLM-written cited answer and states payment and free-trial constraints that affect whether the tool can be used. It does not explain when this deeper, paid workflow is preferable to simpler search or extraction siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds meaningful context beyond them: the x402 payment requirement, the exact price, the required X-PAYMENT header, and per-URL charging for batch calls. It does not cover failure modes such as unpaid requests or rate limits.

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

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

Three tight sentences, front-loaded with what the tool returns and how it is paid for, with the batching rule last. Pricing and header details are dense but each earns its place; no filler wording.

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

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

For a paid, open-world fetch tool with no output schema and no parameter descriptions, the definition covers the core mechanics an agent needs to call it. It falls short on maxChars semantics, error or payment-failure behavior, and any comparison to the many sibling search/crawl tools.

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 has to carry parameter meaning, and it does well for url and urls (max 20, parallel, charged per URL). maxChars is never mentioned in the description or schema, leaving one of three parameters completely unexplained.

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

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

The description gives a specific verb and resource ("Fetch a public URL and return clean markdown") plus the payment mechanism and price, so the agent knows exactly what the tool produces. It never distinguishes itself from close siblings such as search_extract or crawl_site, which leaves a small ambiguity gap.

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

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

It clearly explains the url-versus-urls choice and that batching is parallel and billed per URL, which is real usage guidance. It gives no guidance on when to prefer this tool over crawl_site, search_extract, or web_search, and no prerequisites beyond the payment header.

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/open-world/non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: the call is metered at $0.004 USDC on Base or Solana, requires an X-PAYMENT header, and offers a free trial via X-Trial: 1. What it does not cover is failure behavior when payment is missing or the trial is exhausted.

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

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

Two compact clauses with the output shape front-loaded and the payment terms second — nothing is padded. The payment clause is dense with header names, but each detail is operationally necessary for a paid call.

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

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

Annotations and the inline return-field list mean an agent knows what comes back and that the call is safe, and no output schema is needed. However, with four undocumented parameters at 0% coverage and no note on payment failure or the q-vs-query split, the definition leaves an agent guessing at invocation details.

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% across four parameters, so the description must carry the burden and largely doesn't. 'One query' hints at q/query but never resolves why both exist or which is authoritative, gl (presumably country/locale) is never mentioned, and num is only indirectly implied by 'up to 20'.

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

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

The description names the exact resource and payload ('Image results (title, page url, imageUrl, thumbnail, size) for one query, up to 20'), which lets an agent separate it from web_search, video_search, and news_search without opening the schema. It stops short of an explicit sibling comparison, but the verb+resource+returned-field shape is unambiguous.

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

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

Usage is only implied: an agent infers this is the tool for image results when it needs images rather than web pages or videos. There is no explicit 'use this instead of X when Y' routing, and no guidance on when to burn a paid call versus the free trial (X-Trial: 1) — a real decision point for a metered tool.

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

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

Goes well beyond the annotations: discloses cost ($0.25 USDC on Base or Solana), the two auth mechanisms (X-PAYMENT header, or Bearer xs_ prepaid key), that it is excluded from the free trial, result cap of 20, and the enrichment policy (personal-looking emails dropped, opt-outs honoured). Missing are what happens on payment failure or partial enrichment failures.

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 core capability is front-loaded and every clause carries information, but the first sentence is an unusually long, parenthetically-burdened construction that is harder to parse than it needs to be.

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

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

For a tool with no output schema, it conveys result shape (business listings plus role emails, phones, social links), limits, filtering rules, and the payment model — enough to call correctly. It stops short of describing the response envelope or behavior when payment credentials are 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%, so the schema already documents q, gl, num and location; the description only restates the 20-result cap. It does not clarify the q/query alias relationship or when to supply gl versus location, which is the one ambiguity the schema leaves open.

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 — 'Maps/places businesses for a query and location (up to 20)' — and the enrichment clause ('business contact details only … extracted from each business website and contact page') is precisely what separates it from generic siblings like places_search or search_extract.

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

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

Usage is implied (local business lead generation with contact enrichment) and the payment/trial note is a real selection signal, but no sibling is named and there is no explicit when/when-not guidance such as 'use places_search when you only need listings, not contacts'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: flat pricing at $0.002 USDC on Base or Solana, the x402 X-PAYMENT header mechanism, the alternative prepaid credit key via 'Authorization: Bearer xs_...', and exclusion from the free trial. It stops short of describing pagination or response shape, so it is strong but not exhaustive.

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

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

A single dense sentence front-loads the core action and scan scope, with payment/auth details relegated to trailing parentheticals. Nothing is wasted and an agent can parse purpose and cost without reading further.

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 three-parameter read-only tool with full schema coverage and no output schema, the description covers action, scale, payment, and auth sufficiently to invoke it correctly. The main omission is that it does not confirm what is returned (a flat URL list) nor mention any rate limits on repeated paid calls.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the limit range 1-1000 and default 200. The description corroborates the 1000 cap but adds no syntax or behavioral detail for 'search' or the accepted URL formats beyond what the schema states. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource ('map a website'), the discovery sources (robots.txt sitemaps and on-page links), and the scale cap (up to 1000 URLs). It does not explicitly distinguish itself from the sibling crawl_site, which an agent can only infer from 'discover URLs' vs. crawling.

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

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

Usage is implied by 'discover URLs on a domain', and the description warns that it is not available in the free trial, which is real routing signal. However, it never says when to pick this over crawl_site or search_extract, nor any preconditions on the target site (e.g., must be publicly reachable or have a sitemap).

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 safety is covered structurally; the description goes well beyond that by disclosing the payment mechanism (x402, $0.05 USDC on Base or Solana, X-PAYMENT header), the prepaid credit-key auth header format, and the fact that free-trial credentials will not work. These are exactly the auth/cost facts an agent cannot infer from annotations and that determine call success.

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

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

Purpose and output shape are front-loaded in the first clause, with the payment/auth facts compressed into a compact trailing clause — no filler sentences. The semicolon-chained phrasing packs a lot into one block, which is efficient but slightly dense to parse on first read.

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

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

With no output schema, the description correctly compensates by describing the return shape (top sources per topic plus a compact text digest) and adds the payment/auth prerequisites. It stops short of covering failure behavior — e.g., what an agent sees on a 402 payment-required or expired credit key — which would make a paid tool fully self-sufficient.

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

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

Schema coverage is 100%, so every parameter (gl, num, since, topics) is already documented in the schema. The description only restates the 'since' enum and the 1-5 topic bound, adding no syntax, defaults, or interaction details (e.g., how 'num' interacts with dedupe) beyond the structured fields — baseline 3 applies.

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

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

The description states a concrete output: a deduplicated news digest across 1-5 topics with top sources per topic plus a compact text digest, and names the time-window parameter. An agent can tell this is an aggregated multi-topic digest rather than a raw search, though it never names the closest sibling (news_search) to sharpen the contrast.

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 supplies usage-relevant constraints — the tool is paid, costs $0.05 USDC, and is excluded from the free trial — plus the two accepted credential paths, which materially affect whether an agent should call it. However, there is no explicit statement of when to prefer this over news_search or when not to use it at all (e.g., single-topic lookups, cost-sensitive runs).

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

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

The annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely non-structured behavior: the tool costs $0.004 USDC on Base and requires an X-PAYMENT header, which is critical for an agent to know before calling. It stops short of explaining what happens on a 402 / missing-payment response, which would have made this a 5.

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

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

Three short sentences, front-loaded with the paid/x402 nature and the price before any parameter detail. Every sentence carries information, though the enumeration of freshness values and the num cap duplicates the schema verbatim and could have been spent on the q/query ambiguity instead.

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

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

There is no output schema, so the description is the only place result shape could be explained, yet it says nothing about what a successful response contains (articles, fields, count) or what a 402 challenge looks like. Combined with 9 largely undocumented parameters, a duplicated query slot (q vs query), and no gl/hl locale explanation, an agent has meaningful gaps to guess through.

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

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

Schema description coverage is only 22% across 9 parameters, so the description must compensate, and it partially does — freshness, dateFrom/dateTo, page, and num are called out. However, it mostly restates constraints already encoded in the schema (the freshness enum and the num<=100 maximum) rather than adding meaning, and it leaves the most dangerous ambiguity untouched: the schema exposes both "q" and "query" as separate string parameters with no hint as to which one the search actually uses.

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

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

The description names a specific verb and resource ("News search") plus the transport/payment mechanism (x402). It is clear what the tool does, but it never distinguishes itself from plausible siblings such as news_digest, web_search, or scholar_search, so an agent cannot tell from this text alone why it would pick news_search over news_digest.

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

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

The only usage instruction is mechanical — "Pass an x402 payment in the X-PAYMENT header" — which is a prerequisite rather than guidance on when to use this tool. There is no statement of when to prefer it over the 18 siblings, and no note about when a paid news search is or isn't warranted versus the free web_search or the summarization-oriented news_digest.

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 high-value behavior beyond that: it is a paid x402 endpoint at $0.004 USDC on Base or Solana, it requires an X-PAYMENT header, and X-Trial: 1 yields free trial calls. It does not describe failure modes on payment rejection, which keeps it from a 5.

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

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

Two sentences, front-loaded with the purpose and return fields before the payment constraints. The parenthetical field list and the dual-chain pricing detail are dense but each earns its place. Slightly compressed notation (X-PAYMENT, x402) assumes reader familiarity, but no sentence 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?

With no output schema, the description usefully lists the response fields and the 20-item ceiling, and it discloses the payment requirement that would otherwise block invocation entirely. However, for a tool with 5 parameters at 0% schema coverage, it leaves the q/query and gl/location duplication unexplained and gives no query syntax or location format. Complete on cost and returns, incomplete on inputs.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it only implies that a query string and a numeric cap map to the parameters. It says nothing about the apparent duplicates: both 'q' and 'query' exist, as do 'gl' and 'location', and the description never says which to use or whether gl is a country code versus a free-text locality. That ambiguity is exactly what the description should resolve and 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?

The description names a specific resource (Maps/places results) and enumerates the returned fields (name, address, rating, phone, website, lat/lng), plus a hard cap of 20 results per query. That is enough to separate it from generic siblings like web_search or news_search. It stops short of explicitly contrasting with those siblings, so it lands at 4 rather than 5.

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

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

There is no statement of when to prefer this over siblings such as web_search, answer, or map_site, and no prerequisites or exclusions. The only conditional content is payment mechanics, which is invocation detail rather than usage guidance. An agent must infer the use case from the name alone.

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, openWorld, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: x402 payment of $0.004 USDC on Base or Solana, the required X-PAYMENT header, and a free-trial escape hatch via X-Trial: 1. What it omits is the failure mode when payment is absent (presumably a 402 challenge) and any rate limits, which is why it stops short of 5.

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

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

Two tight sentences: the first front-loads the resource and result shape, the second front-loads the payment requirement. No filler, no restatement of the name or title.

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

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

The description compensates well for the missing output schema by enumerating returned fields, and it fully covers the payment prerequisite. But with four undocumented parameters at 0% schema coverage, the unexplained `gl` and the q/query ambiguity leave a real gap for a tool whose only invocation risk is malformed parameters.

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 all parameter meaning, and it only partially does: "one query" and "up to 20" map to query/q and num, but `gl` is never explained (country/language?) and the duplication of `q` and `query` is left unresolved. An agent cannot tell which of the two query fields to populate or what `gl` expects.

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?

"Scholar results ... for one query, up to 20" names a specific verb+resource and enumerates the returned fields (title, url, snippet, publication, year, citations, pdf), which implicitly separates it from web_search/news_search/image_search. It never names a sibling or states the academic-only scope explicitly, so the differentiation is inferential rather than stated.

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

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

The description gives solid invocation guidance for access (send X-PAYMENT, or X-Trial: 1) and a hard cap of 20 results, but it gives no when-to-use/when-not guidance relative to web_search, news_search, or search_extract. An agent knows how to call it but not clearly when to prefer it over the general search siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive, so the description is not obligated to restate safety. It adds genuinely new behavioral context the annotations do not carry: a per-call cost of $0.02 USDC on base and the requirement to pass an x402 payment in the X-PAYMENT header, which prevents a failed call. It does not state what happens on missing or invalid payment.

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

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

Two dense sentences with no filler, and the payload description is front-loaded ahead of the payment mechanics. It is appropriately sized for the tool, though the parenthetical cost notation is slightly compressed.

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

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

The description does sketch the return shape ('clean markdown of the top N results') in lieu of an output schema and explains the payment flow, which covers the big unknowns. However, with four parameters at 0% schema coverage and a duplicated q/query pair, the definition does not give an agent enough to construct a correct call without trial and error.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it only clarifies that N is bounded 1-5. It says nothing about how q differs from query (both string params, no required fields) or what maxChars controls, leaving an agent guessing about the most error-prone part of the 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?

The description names a specific verb-plus-resource: web search combined with returning clean markdown of the top N results. That composite scope implicitly separates it from the plain web_search and extract siblings, though it never names them explicitly, so an agent must infer the distinction.

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

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

Usage is only implied: the mention of a $0.02 USDC x402 charge signals this is the paid, combined alternative to free siblings like web_search or extract. There is no explicit when-to-use, when-not-to-use, or named alternative anywhere in the text.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description goes beyond them with real behavioral context the annotations cannot express: a hard cost ($0.20 USDC), two payment mechanisms with required headers, and exclusion from the free trial — the main reason a call would fail.

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

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

One dense but front-loaded sentence leads with the capability and its measurable outputs, then a second sentence covers payment and access. Every clause carries information (checks, page cap, score) though the payment sentence is packed tightly enough to require a second read.

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

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

With no output schema, the description carries the burden of telling the agent what comes back — the specific check list, robots/sitemap coverage, brand ranking, and a 0-100 score — which it does. Auth and cost are covered; the only gap is no guidance on alternatives or expected latency for a multi-page audit.

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

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

Schema coverage is 100%, so every parameter is already documented and the baseline is 3. The description reinforces semantics by tying 'pages' to a maximum of 8 audited top pages and 'brand' to brand-query ranking, but it adds nothing for 'gl' (country code) and doesn't explain defaults beyond what the schema states.

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

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

The description names a specific verb+resource (SEO audit of a domain) and enumerates the concrete outputs: search-indexed pages, title/meta/h1/canonical/noindex/alt checks on up to 8 pages, robots.txt and sitemap, brand-query ranking, and a 0-100 score. That level of detail lets an agent distinguish it from crawl_site (raw crawling) or ai_visibility_check without opening either schema.

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

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

It supplies critical usage prerequisites — x402 payment of $0.20 USDC on Base or Solana via X-PAYMENT, or a prepaid Bearer xs_ key, plus the fact it is excluded from the free trial. However, it never states when to prefer this over sibling tools such as crawl_site, competitor_report, or ai_visibility_check, so routing guidance is only implied by the output list.

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

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

Beyond the readOnly/openWorld annotations, the description discloses critical behavior: the tool is paid via x402, costs $0.004 USDC on Base or Solana, and supports a free trial via X-Trial. It also states the result fields and the 20-result cap, though it omits any error/payment-failure behavior.

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

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

The description is compact and front-loaded, first stating the result type and fields, then the result limit, then the payment requirements. Every clause earns its place.

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

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

It covers the key payment/auth model and result shape, which is important given no output schema. However, incomplete parameter documentation and absent alternative-selection guidance leave gaps for an agent trying 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?

With 0% schema description coverage, the description should explain the four parameters. It only indirectly covers 'one query' and 'up to 20', and does not clarify the ambiguous q versus query fields or what gl means.

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 the specific resource and result type: shopping product results with named fields, for one query, up to 20. This clearly differentiates it from generic search siblings, though it does not explicitly contrast against image_search or places_search.

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

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

Usage is implied by 'shopping product results' and 'for one query', so an agent can infer product-search scenarios. However, it gives no explicit when-to-use or when-not-to-use guidance versus web_search, image_search, or other search siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: a per-call price ($0.004 USDC on Base or Solana), the required X-PAYMENT header, and the X-Trial: 1 free-trial escape hatch — the kind of detail an agent cannot infer from structured fields.

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

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

Two sentences, both front-loaded: what you get first, then how to pay for it. No filler, no restating the title beyond the payment qualifier.

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

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

With no output schema and no annotations covering cost, the description rightly covers return fields and payment. But for a 4-param tool at 0% schema coverage, the unresolved q/query duplication and unexplained 'gl' leave an agent guessing at required inputs.

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% across 4 parameters with none required, so the description must compensate. It only clarifies 'num' indirectly via 'up to 20' and says nothing about 'gl' (presumably geo/language) or why both 'q' and 'query' exist — a real ambiguity for a caller.

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 shape: 'Video results (title, url, channel, duration, date, thumbnail) for one query, up to 20.' The resource type alone separates it from image_search, news_search, and web_search, and the listed return fields tell an agent exactly what a call yields.

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

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

Usage is only implied by the resource name; there is no explicit 'use this instead of news_search when...' routing despite many sibling search tools. The payment/trial mechanics give practical call context, but the choice between this and sibling search tools 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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the x402 payment mechanic, the exact price ($0.004 USDC on base), the header names, and the 25-call free trial per network. It says nothing about response shape, error behavior on unpaid requests, or rate limits beyond the trial cap.

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

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

Two sentences, front-loaded with the payment model since that gates invocation, followed by supported options. No filler, though the parameter list largely duplicates schema constraints that an agent can already read.

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

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

For a 9-parameter tool with zero required parameters and no output schema, the description covers the payment gate well but leaves real ambiguity: an agent cannot tell from the text that a query is needed to get results, nor what gl/hl do. Nothing about the return value is required here, and none is given, which is acceptable.

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

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

Schema description coverage is only 33%, so the description must compensate, and it only partly does: it enumerates the freshness values and the page/num bounds, but those are already in the schema as enum and maximum. The two genuinely undocumented parameters, 'gl' and 'hl' (geo and language), are never explained, and the description is silent on the q/query alias and on the fact that no parameter is actually required.

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 ('Paid web search') plus the payment rail and price, which is more than a restatement of the name. It does not differentiate from the many sibling search tools (news_search, scholar_search, image_search, batch_search), so an agent must infer that this is the general-purpose one.

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 explains how to pay (X-PAYMENT header, or X-Trial: 1 for 25 free calls per network) but never says when to choose this over the 18 sibling search tools. There is no guidance on eligibility, what happens when the trial is exhausted, or when a specialized sibling is preferable.

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