robotbase-dev

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing the return envelope, including an 'errors' field that signals partial-failure behavior across multiple upstream sources. It does not mention rate limits or per-source failure isolation, which is why it stops at 4.

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 for when-to-use, exclusions and return shape. No filler sentences; every clause either scopes the data sources or routes the agent.

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-required-parameter read tool with no output schema, the description supplies both scope and return shape, which is close to complete. The remaining gap is behavioral ordering/aggregation when ecosystem=all and the meaning of the limit across multiple sources.

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%; 'limit' and 'ecosystem' carry no field-level description. The description partially compensates by naming the source families, which map onto the ecosystem enum values, but says nothing about the limit default/cap or how 'all' aggregates results, so the gap is only half-closed.

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

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

Names a specific resource domain and enumerates the five underlying sources (GitHub, Hugging Face, npm, PyPI, Hacker News), so an agent knows exactly what data it returns. It also distinguishes itself from web_search and social_hot by name, removing ambiguity against 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 'When to use' triggers (choosing a library/model, adoption signals, package health) and explicit 'Do not use' exclusions routing to web_search and social_hot. 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?

Adds substantial context beyond annotations: the full return object shape, the 10-action cap, that screenshot returns MCP image content, and the metering model (shared 100/day free bucket, then 3 credits/call over x402). There is mild tension with readOnlyHint=true given form-submit/typing capability, but the framing is interaction-with-a-public-page rather than a state-changing API call, so it is not a direct contradiction. A note on what happens when an action fails mid-sequence would complete it.

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

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

Front-loads the core action, then uses labeled 'When to use', 'Do not use', 'Returns', and metering clauses. Dense but every sentence carries operational information; nothing is redundant with 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?

Strong for a complex tool with no output schema: it spells out the return fields (ok, url, final_url, title, markdown, chars, elapsed_ms, screenshot?, xhr?, took_ms, _metering), the action limit, and cost. The remaining gap is how per-action error/failure is surfaced within {ok, ...} and what happens if one of the 10 actions fails.

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 all six parameters and their defaults are already documented. The description only restates the 10-action maximum (already in maxItems) and adds that screenshot yields MCP image content; it adds no per-action syntax detail (e.g. selector vs text target for click/type) beyond what the schema hints at.

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 ('drive a real Chromium browser') plus resource ('one public page') and enumerates the interaction primitives: click, type, press keys, scroll, wait for selectors. It explicitly contrasts itself against web_fetch and web_crawl, so the agent can distinguish it 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?

Provides explicit 'When to use' (content hidden behind cookie banners, tabs, 'load more', form submit that web_fetch/web_crawl cannot see) and explicit 'Do not use' (plain reading -> web_fetch, bulk crawling -> web_crawl, no login/paywall bypass). This is the when/when-not/alternatives trifecta.

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 material context beyond them: robots.txt compliance, SSRF guards, partial-failure skipping, same-host enforcement, and exact metering terms (shared 100/day free bucket, 3 credits over x402, no API key). This is precisely the behavioral disclosure an agent needs before spending quota.

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 When/Do-not/Returns/Behavior/Metering segments. Despite being information-dense, every sentence carries a distinct operational fact with 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?

No output schema exists, yet the description spells out the exact return object shape ({ok, url, final_url, count, pages[...], cached, took_ms, _metering}) and notes partial failures are skipped. Combined with metering and safety notes, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so url, depth, max_chars, and max_pages are already documented. The description reinforces the depth range and page cap but adds no new per-parameter semantics (no guidance on when to choose depth 1 vs 2 or how max_chars affects cost), so the baseline 3 applies.

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

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

States a specific verb and resource ('Crawl one site's same-host pages starting from a URL') with scope bounds (depth 1-2, ≤20 pages) and names what it returns. It is immediately distinguishable from web_fetch (single page) and web_map (URL listing) by explicit sibling naming.

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 'When to use' condition (several pages from one site: docs section, news index, product list, and web_map is insufficient) and an explicit 'Do not use' clause routing single pages to web_fetch and full mirrors away. Alternatives and exclusions are both stated, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description still adds substantial context beyond them: the metering model (100 calls/day free bucket per IP, then 3 credits per submit over x402), the 24h idempotency-key retry window, and the exact return shape. This is exactly the kind of operational context 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?

Dense but well-structured, with a clear purpose sentence followed by labeled when-to-use, when-not-to-use, returns, and metering sections. No sentence is filler; even the metering note is decision-relevant.

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 only 5 params at full schema coverage, no output schema, and rich annotations, the description is fully sufficient: it tells the agent what happens, how to poll, how to retry idempotently, and what it costs. Nothing needed to invoke 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 ranges and defaults for depth, max_chars, and max_pages are already documented in the schema. The description's note on idempotency_key ('retry safely, 24h window returns same job') largely repeats the schema text, adding little new semantics. 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 ('Submit a same-host crawl as an asynchronous job') plus the immediate return of job_id. It clearly distinguishes itself from web_crawl (synchronous), web_fetch (single page), and web_crawl_job (polling) by name.

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

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

Explicitly gives when-to-use (more than a couple of pages, can't hold a long request, then poll web_crawl_job until done/failed/cancelled) and when-not-to-use (one page → web_fetch; need result in this call → web_crawl). The alternatives are named with the condition that selects each.

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

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

Adds real context beyond annotations: free/not metered, rate-limited, the full status object shape, and that a done result matches web_crawl's shape. One residual tension is left unaddressed: readOnlyHint=true while action=cancel stops a running job, so the description should clarify that cancel only terminates the job and does not alter fetched data or crawl results.

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

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

Purpose, when-to-use, when-not-to-use, and return shape are ordered by decision value, with no filler sentences. The inline return-shape list is dense but earns its space given there is no output schema.

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

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

For a two-parameter control tool with no output schema, the description covers the lifecycle, terminal states, progress fields, error field, cost, and rate limiting — everything needed to call it and interpret the response 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% and the enum already documents 'Poll status (default) or cancel the job', so the description largely restates it via 'poll with action=status' and 'action=cancel to stop a running job'. It adds the polling-until-terminal-state habit, but no format or edge-case detail about job_id 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?

Opens with a specific verb pair and resource ('Check or cancel an asynchronous crawl job') and ties it back to the creating tool, web_crawl_async. An agent can distinguish it from web_crawl_async, web_fetch, and web_monitor_* 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 'When to use' names the polling pattern and termination states, and explicit 'Do not use' names the two alternatives (web_crawl_async to start, web_fetch for quick single-page reads) with the condition that selects each. The action=status vs action=cancel split is spelled out.

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

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

Goes well beyond the annotations: discloses the 6h page cache and what fresh=true does to it, that snapshots are persisted per URL in SQLite with only the latest kept, and the metering model (shared 100 calls/day free bucket per IP, then 1 credit via x402). The baseline-persistence side effect is disclosed even though it is arguably a write to internal state; readOnlyHint refers to the external target page, so this is a disclosed nuance rather than a contradiction.

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

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

Front-loaded with purpose, then clearly delimited 'When to use', 'Do not use', and 'Returns' blocks, followed by cache and metering notes. The long return-field list is justified because no output schema exists, and no sentence is redundant.

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

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

For a stateful, metered, cache-coupled tool with no output schema, the description covers the state model, the return shape field-by-field, cache interaction, and pricing. Nothing an agent needs in order to call it correctly and interpret the result 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 real semantics on top by explaining the behavioral consequence of fresh (cache-busting query vs. comparing cached content) and by tying the tool's core semantics to max_chars-style truncation. It does not add specifics for max_chars itself, keeping it short of 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?

Opens with a specific verb+resource+mechanism: fetch a page now and compare against the previous snapshot of the same URL, returning changed flag and unified diff. It explicitly distinguishes itself from web_fetch and web_extract_schema by name, so an agent can route without opening sibling 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?

Has explicit 'When to use' (monitoring prices, docs, policy pages, SEO titles/meta) and an explicit 'Do not use' section naming the two alternative tools and the conditions that select them. It also states the statefulness rule: first call stores the baseline, later calls return added/removed lines.

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

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

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses metering and cost (shared 100 calls/day per IP free bucket, then 1 credit per call over x402) and the caching signal in the response. That is genuinely actionable context an agent cannot get from the annotations.

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

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

Front-loaded with purpose, then use/avoid, then returns, then metering — a sensible ordering. The dense return-shape string is somewhat heavy for a description, though it earns its place given no output schema exists.

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

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

With no output schema, the description enumerates the response shape (ok, url, title, meta subfields, jsonld, tables with caption/headers/rows, links, cached, took_ms) and covers cost. An agent has everything needed to call and interpret 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 coverage is 100%, so url and include_links are already documented. The description adds nothing about parameter semantics; the only hint ('links?') merely mirrors the include_links option in the return shape. 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?

Specific verb and resource ('Extract structured data from one public page') followed by an enumeration of exactly what is extracted (tables, JSON-LD, OG/Twitter/canonical/lang metadata). It is clearly distinguishable from web_fetch, web_metadata, and web_extract_schema by the stated payloads.

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

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

Explicit 'When to use' (page has tables or schema.org JSON-LD needed as data, without an LLM) and explicit 'Do not use' routing to web_fetch for text and web_screenshot for images. Alternatives are named with the selecting 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 only cover read-only/idempotent/open-world, but the description adds materially new context: no-LLM extraction, the Open Graph/meta fallback with matched=false, and the metering model (100/day free bucket then 1 credit via x402). It also documents the return payload shape, which no output schema supplies.

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 when/when-not, then returns and pricing in clearly segmented clauses. The returns object listing is dense but each field is informative; nothing is wasted, though the brace dump is borderline verbose.

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 proactively supplies the exact response shape, the fallback condition, and cost model for a metered open-world call. An agent has everything needed to invoke correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning by listing which fields each schema type yields and noting 'auto' detection from JSON-LD types. It slightly exceeds what the enum table conveys without duplicating 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 verb+resource ('extract a page's structured data into a named schema') and enumerates the supported schema types, so an agent knows exactly what this returns. It also names the sibling tools it is not (web_metadata, web_extract, web_fetch), making differentiation immediate.

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

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

Has explicit 'When to use' with concrete field examples (title/author/date, price/availability, FAQ Q&A) and an explicit 'Do not use' clause naming the alternatives for verbatim JSON-LD and raw text. Routing 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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds context they cannot: the full return shape, that summaries are HTML-stripped and capped at 500 chars, caching behavior via the `cached` field, and metering specifics (shared 100 calls/day per IP free bucket, 1 credit per call over x402, no API key). That is real operational context for a rate-limited external 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-loaded with purpose, then usage, then return shape, then metering - the order matches how an agent needs to consume it. Every sentence carries distinct information; even the metering line prevents a failed call loop.

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

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

No output schema exists, but the description enumerates the return object's fields, documents the summary truncation, and discloses cost limits - which is everything an agent needs to call this correctly and interpret 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% and both parameters (url with 2048-char cap, limit 1-20 default 10) are fully documented in the schema. The description adds nothing parameter-specific, so the baseline 3 applies.

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

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

Opens with a specific verb+resource ('Read an RSS or Atom feed and return its latest items') and explicitly names the sibling tools web_fetch and web_map as the wrong choice for adjacent tasks. An agent can distinguish it from every other web_* tool without opening a schema.

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

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

Gives an explicit 'When to use' condition (user wants latest posts/news, or a feed URL is known and headlines+links are wanted) and an explicit 'Do not use' with the two correct alternatives for article text and URL discovery. 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?

Despite annotations already declaring readOnly/idempotent/openWorld, the description adds real operational context: robots.txt compliance, no login/paywall bypass, direct-fetch-then-provider fallback with source=provider, caching, and per-call metering (100 free calls/day per IP, then 1 credit via x402, 402 carries accepts[]). It also describes the return payload in detail even though no output schema exists. The one blemish is an internal conflict: it says responses are 'capped at 12000 characters' while the schema documents max_chars defaulting to 8000, which could mislead about actual truncation 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?

Well front-loaded: what it does, then when, then when not, then returns, then limits/metering — a reader can stop after sentence one. It is dense and slightly overlong on metering detail, but almost every sentence carries information an agent needs; only the pricing sentence could be trimmed.

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

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

There is no output schema, and the description compensates by enumerating the return fields (url, final_url, status, title, content, chars, truncated, fetched_at, source, cached, took_ms) and explaining truncation. It also covers auth ('no API key'), rate/credit limits, and failure path (402 with accepts[]), so an agent can call it and interpret the result without further lookups.

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; url, format and ocr semantics are already fully documented in the schema. The description only adds guidance for max_chars (raise up to 20000 for more content), and that guidance partly contradicts the schema's stated default of 8000 by implying a 12000 cap. Enum for format is documented in the schema, not the description.

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 ('Fetch one public web page') plus the transformation applied (readable text as markdown/plain text, boilerplate stripped). The scope word 'one public web page' immediately separates it from web_crawl, web_map and web_fetch_batch.

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

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

Has an explicit 'When to use' clause keyed to having a specific URL, an explicit 'Do not use' list (crawling/mirroring, login-gated or paywalled pages, API/RPC endpoints, book text), and names the correct sibling for the last case (cyberlibrary_get_chapter). That level of routing detail is rare and leaves little inference to the agent.

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/open-world/non-destructive, and the description adds a lot on top: partial failures don't fail the whole call, metering is one call per URL against a 50/day free bucket shared with web_fetch, then 1 credit per URL over x402, max 5 URLs, no API key. This is unusually rich behavioral disclosure.

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

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

Front-loaded with purpose, then labeled 'When to use', 'Do not use', 'Returns', and metering sentences. Dense but every clause is load-bearing; only the metering detail is slightly verbose for a description field.

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

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

No output schema exists, and the description compensates by enumerating the return object fields (ok, count, ok_count, results with url/final_url/status/title/engine/chars/snippet, took_ms, _metering). Combined with metering and partial-failure semantics, an agent has everything needed to call and interpret it.

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 practical meaning: it explains the ~1200-character snippet length (the max_chars default) and the 5-URL cap in terms of triage use. It does not document the format enum's effect 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?

States a specific verb (fetch) plus resource (up to 5 public URLs) and the exact output shape (title, engine, ~1200-char snippet), framing the goal as triage. It explicitly differentiates itself from web_fetch and web_map by name.

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

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

Gives an explicit when-to-use scenario (search returned several candidates, want a first pass) and a named follow-up tool (web_fetch for full text), plus a 'Do not use' clause routing crawls to web_map. Both positives and exclusions 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?

Adds substantial context beyond annotations: sitemap-first strategy, same-host link discovery, max 50 URLs, no page content, robots.txt compliance, full return shape, caching, and detailed metering (100 calls/day shared bucket, 1 credit over x402, no API key, 402 accepts[]). Annotations already cover safety, but the description provides the operational behavior 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 purpose, then usage, then return shape, then metering. Every sentence carries actionable information; the metering detail is dense but necessary for a paid tool. 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?

Given no output schema, the description explicitly describes the return object fields including urls with source tags, cached, took_ms, and metering. It covers safety boundaries, scope, and cost — everything an agent needs to call correctly.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema. The description repeats the 50-URL limit and URL source behavior, which is marginally useful, but adds no syntax or format detail beyond the schema. 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 (discover URLs of one site) and explicitly distinguishes itself from crawler siblings, naming the exact boundary (max 50, no page content). An agent can identify this tool's job 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?

Provides explicit 'when to use' and 'do not use' sections, naming the alternative pattern (web_crawl) and the robots.txt constraint. It tells the agent both the positive trigger (needing a page list before fetching) and the anti-pattern.

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 (readOnly, idempotent, non-destructive, openWorld), so the description adds metering and cost behavior: a shared 100 calls/day free bucket across all web tools, then 1 credit per call over x402 with no API key. That is genuinely useful operational context. It omits failure behavior (what happens on non-HTML or blocked pages) and whether 'cached' implies staleness, keeping it below 5.

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

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

Front-loads purpose, then labeled When-to-use / Do-not-use / Returns / Metering blocks. Dense but every line carries distinct information an agent needs; 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?

For a single-parameter read tool, the description covers purpose, routing, the full return shape (compensating for the absent output schema), and metering constraints. Nothing material to 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?

There is only one parameter and schema coverage is 100%, with the schema itself documenting the http(s) URL and 2048-char limit. The description adds no further parameter guidance, so baseline 3 applies.

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

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

States a specific verb (Extract) and resource (page's structured metadata), then enumerates exactly the field families returned (OG, Twitter cards, canonical, language, JSON-LD). It is clearly distinguishable from web_fetch and web_screenshot by the explicit do-not-use routing.

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

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

Gives a concrete when-to-use condition ('you need title/description/author/image ... or JSON-LD for a product/article, without reading the whole page') and explicit exclusions pointing to named siblings web_fetch and web_screenshot for text and screenshots respectively.

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 says the tool deletes a monitor and removes its event history, which is a destructive write operation. The annotations declare readOnlyHint=true and destructiveHint=false, directly contradicting the described behavior. Although the description adds useful details like cascade deletion, rate limits, and error behavior, the core mutation semantics conflict with the structured annotations.

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

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

The description is compact and front-loaded: deletion scope and cascade effect come first, followed by usage guidance, return shape, error behavior, and rate limits. Every sentence carries operational value.

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

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

There is no output schema, but the description supplies the return shape, the error case for unknown or foreign ids, cost information, and rate limits. For a single-parameter tool, this is sufficiently complete, aside from the annotation contradiction.

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

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

Schema description coverage is 100%, and the schema already documents that monitor_id is the id returned by web_monitor_set. The description does not add meaningful semantics beyond what the schema provides, so the baseline of 3 for full schema coverage 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: deletes one scheduled change monitor owned by the calling IP, and explicitly notes the cascade removal of event history. This distinguishes it clearly from web_monitor_set and web_monitor_list.

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

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

Explicit when-to-use conditions are given (user no longer needs monitoring, per-IP limit reached), plus an explicit when-not-to-use case with the alternative: there is no pause, so delete and re-create. This is unusually complete 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 already cover read-only/idempotent/non-destructive, and the description adds the traits annotations can't: ownership is scoped to the calling IP, the call is free but rate-limited to 20 calls/min, and passing monitor_id unlocks the last diff. The full return object shape is spelled out. This is genuinely additive behavioral context.

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

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

Front-loaded with purpose, then usage, then returns, then cost — a sensible ordering. The inline return-shape enumeration is dense and slightly heavy, but every element conveys something an agent needs.

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 compensates by enumerating the returned object including nested monitor fields and the events array. With rate limits, ownership scope, and the monitor_id variant all covered, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented; baseline would be 3. The description still adds value by tying monitor_id to the concrete outcome (single monitor plus last_event.diff, up to 4000 chars), which the schema does not state.

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 ('List the scheduled change monitors') with an explicit scope ('owned by the calling IP') and enumerates the returned fields. It also names the siblings it is not (web_monitor_set, web_diff), so an agent can distinguish it without opening a schema.

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

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

Explicit when-to-use ('after web_monitor_set, poll this instead of re-fetching') and an explicit 'Do not use' clause naming the correct alternatives for creation and one-off comparison. 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 itself is unusually rich — webhook contract (https only, no redirects, 8s timeout, 2 retries at 30s/120s), HMAC signature header, first-check timing, limits (15–1440 min, 5 per IP, 7-day expiry) and metering. However it describes a state-creating operation ('Create... stores a new snapshot and records a diff event') while annotations declare readOnlyHint=true and idempotentHint=true; registering a monitor is a persistent write with quota/expiry consequences. The description is more accurate than the annotation, which limits practical harm, but the conflict is real.

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

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

Dense but front-loaded: purpose first, then use/do-not-use, then returns, webhook contract, limits and cost. Every sentence carries operational information, though the single unbroken block would scan better with the labeled sections broken into lines.

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 still specifies the return shape ({ok, monitor_id, url, status, interval_minutes, next_check_ts, webhook_enabled, ...}), where change events surface (web_monitor_list.recent_events), the baseline timing, and the cost. An agent has everything needed to call this correctly and set expectations.

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 documents all three params, so the baseline is 3; the description adds genuine meaning on top: webhook must be https with no redirects, the interval bound 15–1440, the max-5-monitors-per-IP cap, and the exact signature header format. What it does not clarify is override/duplicate behavior when the same URL is monitored twice.

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 ('Create a scheduled change monitor for one public URL') and immediately explains the mechanism: re-fetch on interval, store snapshot, record diff event. It also names the siblings it is not (web_diff for a one-shot comparison, web_fetch for a single read), so an agent can discriminate 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 'When to use' block with concrete triggers (price, docs, policy page, job post, release notes, 'watch this for me') and an explicit 'Do not use' block routing to web_diff and web_fetch with the selecting condition. This is the textbook when/when-not/alternative structure.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations: real Chromium rendering, robots.txt respect, SSRF guarding, a 3MB per-image cap, and full metering terms (100/day shared free bucket across twelve web tools, then 2 credits via x402, no API key, 402 response carries accepts[]). These are exactly the operational facts an agent needs before calling a network-dependent paid tool.

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

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

Front-loads purpose, then when-to-use, exclusions, return shape, and metering in a logical order with clear labels. It is dense but every clause carries information; the metering sentence is long yet operationally necessary since no API key exists.

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

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

No output schema exists, and the description compensates by naming the return payload: image/jpeg content plus url, final_url, title, width, height, bytes, engine, elapsed_ms, and _metering. Combined with documented failure/metering behavior, an agent has everything needed to call and interpret 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 url, width, height, and full_page are already fully documented with ranges and defaults. The description adds only the implicit 'one public web page' single-URL constraint and no per-parameter meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Capture a screenshot of one public web page as an image (JPEG) plus metadata') and explicitly scopes it to a single page. It is clearly distinguishable from web_fetch and bulk-capture siblings, which are named in the exclusion clause.

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 when-to-use condition ('visual layout matters – a dashboard, chart, UI state') and explicit when-not-to-use cases, naming the alternative for text reading ('use web_fetch'). Login, paywall, and bulk capture are ruled out by name rather than 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 the description adds substantial context beyond them: a SearXNG-first provider chain with automatic Serper/Tavily/bing_rss fallbacks, a 10-minute cache that still bills as a call, and a metering model (100 free calls/day per IP, then 1 credit via x402, no API key, 402 carries accepts[]). These are exactly the operational traits 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?

Front-loaded with purpose, then when-to-use, then exclusions, then operational details in a predictable order. Dense and mostly waste-free, though the returns-shape block and the max-count sentence sit slightly awkwardly after the metering discussion.

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, and the description compensates by spelling out the response object, including provider, cached and took_ms fields. Caching, metering, fallback behavior and result limits are all covered, leaving nothing an agent needs in order 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 every parameter (lang, site, count, query, freshness) is already documented in the schema. The description's only parameter remark, 'max count is 10', restates the schema's 1-10 range and adds nothing new. 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 and resource (search the live web) plus the exact return shape (title, URL, snippet, published date). It explicitly distinguishes itself from the sibling tools an agent might confuse it with: web_fetch, the on-chain tools, and cyberlibrary_fulltext_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?

Provides concrete use-case examples in the agent's own voice ('recent Zcash governance proposals'), an explicit ordering rule ('use it before web_fetch, then fetch the one URL that looks authoritative'), and a 'Do not use' section that routes to named alternatives with the condition that selects them.

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