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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial context beyond them: it is a paid tool requiring a wallet key, pays per call in USDC with a per-call cap and session limit, returns a payment receipt and portal envelope with untrusted data, makes no network call when no key is present, and falls back to a self-hosted API. It also notes 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?

The definition is front-loaded with purpose and usage before payment and safety details, and every sentence contributes operational information. It is somewhat long and could be split into clearer clauses, but the density is justified by the tool's complexity.

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, paid, network-fetching tool with no output schema, the description covers return fields, error shape, payment mechanics, authentication requirements, fallback behavior, and untrusted-content warnings. Nothing an agent needs in order to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description does not add syntax or format details beyond what the schema provides for url, formats, or max_chars; it only summarizes the return shape. Baseline 3 is appropriate when the schema carries the 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?

The description states a specific verb and resource (fetch one absolute URL with AgentSearch Web Extract) and enumerates the returned fields. It explicitly differentiates itself from agentsearch_web_search and agentsearch_render, so an agent can select it without opening the schema.

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

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

It gives explicit when-to-use conditions (already have the page URL and need its body) and names alternatives for the two main cases: finding pages from a query and JavaScript-rendered content. Nothing is left to inference.

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

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

The description adds tremendous value beyond annotations, detailing the hard deadline (4.2s), rate limit mechanics (HTTP 429), full read-only behavior, and specific error categorization (Target-site failures vs. MCP errors). Furthermore, it details the payment logistics (wallet requirements, per-call cost, self-hosting alternative).

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 excessively long and unstructured, conflating high-level usage guidance with deep technical constraints, billing policies, and detailed error handling. Its immense size makes it difficult to parse quickly.

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 inherent complexity of web rendering, payment infrastructure, and specific error conditions, the description is exceptionally complete. It leaves almost no ambiguity for an agent regarding prerequisites or operational constraints.

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 input schema provides 100% coverage, which already documents all parameters. The description provides high-level context on the tool's operation but does not need to add specific semantic meaning to the individual parameters beyond what the comprehensive schema delivers.

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

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

The description clearly states the core action (render URL in headless Chromium) and distinguishes it from `agentsearch_extract` by highlighting its ability to run JavaScript and capture client-rendered content.

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 usage context: use for JS-heavy apps (SPA, dashboards), prefer `agentsearch_extract` for static pages, and `agentsearch_web_search` for discovery. This is maximally instructive.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: down services are hidden unless include_down is true, board/network failures (HTTP 429) surface as MCP errors, no API key or AGENTSEARCH_BASE_URL is needed, and AgentSearch's own services get no ranking boost. The untrusted_note prompt-injection warning is exactly the kind of safety disclosure annotations cannot carry.

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

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

Front-loaded with the call-to-action and free of filler, but it is one dense run-on paragraph with stacked parentheticals (env var defaults, category list). It earns nearly every sentence, yet light structure would make the mode switch and error behavior easier to scan.

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

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

With no output schema, the description carries the return contract itself: ranked fields (id, status, uptime_24h, p50 latency, price_usd, review counts/labels) and the single-service variant. Error behavior and configuration prerequisites are also covered, leaving little an agent needs 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 100%, so the baseline is 3; the description still adds value by explaining that include_down controls whether 'down' services appear and that service_id switches from a ranked list to single-service mode (with 7-day probe history and reviews). It does not add anything for max_price_usd, network, or limit beyond their schema text.

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

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

Specific verb ('look up') plus a named resource ('AgentSearch Review Board') with explicit scope: which services work right now for a task across Pocket, x402 and remote MCP servers. It is clearly distinguishable from the sibling execution tools (agentsearch_web_search/extract/render) and from agentsearch_review_submit, which it names as the counterpart.

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

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

Gives an explicit trigger ('Look up before choosing a tool'), an alternate mode ('Pass service_id instead of task'), and a follow-up path ('After you use a service, report how it went with agentsearch_review_submit'). The 'when not to use' side is implied by the named alternative for submissions.

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 far beyond the annotations: anonymity by default, rate limits (5/day, 1 per service per day), the AGENTSEARCH_REVIEW_KEY prerequisite for weighted reviews, the 7-day called_at window, note sanitization/truncation, and the returned fields (review_id, weight_tier, status, flags). None of this is derivable from readOnlyHint=false / idempotentHint=false / openWorldHint=true.

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 and the two required fields before optional detail, and every sentence carries operational information (rate limits, key behavior, return values). The density is high and borders on cramped in a single block, but there is little actual waste.

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

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

For a 10-parameter write tool with no output schema, the description covers everything an agent needs: prerequisites, defaults, limits, sanitization, auth/weighting, moderation outcomes, and return value shape. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: latency_ms bounded 0–120000, called_at must be within 7 days, note is stripped of URLs/markup/code and stored to 280 chars, and proof_tx_hash is an x402 payment on Base. Minor residual tension between the description's '280 characters' and the schema's maxLength of 1000, though they are reconcilable (truncation on storage).

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 ('post a short structured review of a service you just called') plus the intent (so other agents can see what works). The closing line distinguishes it from siblings explicitly: it writes to the board and 'does not call or pay the reviewed service,' which separates it from agentsearch_web_search/extract/render and from agentsearch_review_lookup.

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

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

Gives a clear trigger ('Submit after using one') and ties the required service_id to agentsearch_review_lookup, implying the lookup-first workflow. It stops short of naming explicit when-not-to cases (e.g., don't submit without having called the service, don't use for private/unobserved results), so it is clear context without full exclusions.

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

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

Beyond the annotations, the description discloses free-tier limits (25 searches/day per IP), paid-mode pricing and caps, self-hosted behavior, rate-limit semantics for 429 responses, payment receipt/envelope handling, and that paid portal data is untrusted third-party content. These are substantive operational details not captured by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

The description is front-loaded with purpose and usage guidance before moving into operational and payment details. It is dense and somewhat lengthy for a two-parameter search tool, but the length is largely justified by the behavioral transparency it provides.

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, the description explains the return format, paid-mode envelope, payment receipt inclusion, and operational failure behavior. It is complete enough for an agent to understand both how to call the tool and what to expect from 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 both parameters are already documented in the input schema. The description repeats the max_results clamping behavior and default, but adds little semantic detail beyond the schema's own parameter descriptions.

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

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

The description states a specific verb and resource: 'Search the web with AgentSearch' and return pretty-printed JSON. It also explicitly distinguishes this tool from URL-based siblings by directing agents to agentsearch_extract or agentsearch_render when a URL is already available.

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

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

It gives explicit when-to-use guidance: use this when you have a query and need hits rather than a page body. It also names alternatives and their conditions, including agentsearch_extract for existing URLs and agentsearch_render for JavaScript-heavy pages.

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