robotbase-content

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds the return envelope including an errors[] channel, which usefully warns that partial-source failures are possible. It could still say whether sources are fetched in parallel or degrade independently (e.g. does a failing Ngram abort the call), which would push this to 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 tight clauses — sources, when to use, when not to use, returns — each earning its place, with the highest-value routing information front-loaded.

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?

All four parameters are optional with sane defaults, and the description covers sources, use cases, exclusions, and the return shape; only the per-parameter behavior (limit scope, geo semantics) is thin, which is a modest gap for a read-only aggregator.

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 only 25% — only query is documented — but the return key list ({query, geo, trending[], pageviews, ngram, errors}) implicitly maps to the include enum values, and 'regional' hints at geo. Still, limit, the geo format expectation, and the meaning of include=all vs individual values are left to the schema alone.

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 the concrete sources it aggregates (Google Trends RSS, Wikipedia pageviews, Google Books Ngram) and the kind of question it answers, which cleanly separates it from web_search or cyberlibrary search siblings.

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

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

Gives explicit when-to-use triggers (topic rising, long-term attention, regional trending, evidence of public interest) and an explicit do-not-use clause naming the two siblings (social_hot, prediction_market_odds) that cover adjacent needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds beyond that: it fixes the cardinality ('exactly one book'), clarifies the lookup key is lang+slug, and states the return shape ('one catalog record object'), which helps the agent plan a fetch decision. No mention of auth or rate limits, so not a full 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-loaded with the core identity, then labeled When-to-use / Do-not-use / Returns segments. Every clause carries routing or expectation-setting information; there is no filler.

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

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

With no output schema, the description compensates by enumerating the returned fields and stating the return shape, so the agent knows what it will get. Combined with the routing guidance, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100% and both parameters (lang, slug) are documented there, so the schema does the heavy lifting. The description only implies the lang+slug requirement in prose without adding format or validation detail beyond what the schema already says. Baseline 3 is correct.

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

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

States a precise verb+resource: returns metadata for exactly one book, and enumerates the fields (title, author, genre, chapter_count, word_count, source URL, access URLs). It also names the sibling tools it is not (cyberlibrary_get_chapter, cyberlibrary_get_markdown), so an agent can route without opening any schema.

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

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

Explicit 'When to use' conditions (you have lang+slug and need to judge whether a book is worth fetching, or need chapter_count before pulling a chapter) and an explicit 'Do not use' clause pointing at the two content-retrieval siblings. Both the trigger and the exclusions are stated, not inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value beyond these by spelling out the return shape ({generated_at, total_items, readable_items, languages[]}) and the ordering role of the call, though it says nothing about rate limits or the size/cost of the catalog response.

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

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

Front-loads the purpose, then routes with labeled 'When to use' / 'Do not use' clauses and closes with the return shape. Every sentence carries distinct information; no filler or repetition of the title.

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

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

There is no output schema, and the description compensates by enumerating the top-level return fields and the per-language entry contents. Combined with annotations covering the safety profile, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter syntax for the description to clarify, and it correctly describes the returned fields instead.

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: indexing 'Every language catalog in Cyber Library with item counts and the corpus generation date.' It distinguishes itself from siblings by explicitly naming cyberlibrary_language_shard and cyberlibrary_get_markdown/get_chapter as different tools, so an agent can route without opening a schema.

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

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

Explicit 'When to use: first call in any session' with the reason (to pick a language before fetching a shard), plus a 'Do not use' clause naming the correct alternatives for each excluded case. Both when and when-not are covered with named substitutes.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description adds useful context about what is returned (including a public-domain territory notice and license), but discloses nothing new about behavior beyond that – no auth needs, rate limits, or edge cases. A 3 is appropriate against a full annotation set.

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

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

Front-loaded with the core purpose, then clearly subdivided into 'When to use', 'Do not use', and 'Returns'. Every clause earns its place with no filler.

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

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

For a read-only citation helper with no output schema, the description lists the return fields so the agent knows what it gets, and usage boundaries are clear. The only real gap is the undocumented lang/slug parameters, otherwise complete.

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% and the two required parameters (lang, slug) are documented nowhere. The description never explains what these identifiers mean or their expected format, so it fails to compensate for the coverage gap despite being the only source of parameter meaning.

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 (cite) plus resource (one book) and enumerates the exact fields produced (title, author, page_url, license, notice). It also names the sibling it is not (cyberlibrary_get_chapter), so an agent can place it precisely among the ~60 tools.

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

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

Explicitly gives both sides: 'When to use: before quoting or summarising a book, so the answer carries a verifiable source' and 'Do not use: to fetch content (use cyberlibrary_get_chapter)'. The alternative is named with the condition that selects it, leaving nothing to inference.

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

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

Annotations already carry readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further with corpus size (26 GB), the 79%/20.4 GB English-language weighting, and the 10-100x speed/relevance payoff of language scoping — genuinely useful behavior beyond the annotations. It stops short of discussing auth or rate limits, but those are minor here.

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

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

Front-loaded with purpose, then usage, then the returns shape; every sentence carries operational information. The dense inline returns block is slightly heavy, but with no output schema it 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?

For a four-parameter search tool with no output schema, the description supplies the return structure (query, lang, results with book/chapter/source_url/match/snippet), scoping advice, and the sibling alternative — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema documents all four parameters (baseline 3). The description adds the rationale the schema lacks — why lang matters (79% of corpus, 10-100x faster) — which meaningfully guides parameter choice beyond the raw field docs.

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

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

States a specific verb and resource (full-text search inside actual book text over a 26 GB Markdown corpus) and explicitly distinguishes itself from the title-lookup sibling cyberlibrary_search_books. An agent can identify the tool and its scope 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?

Gives explicit when-to-use ('locate where a phrase, name or quotation occurs... or ground an answer in a verifiable passage') and when-not ('to find a book by title — call cyberlibrary_search_books, which is far cheaper'), plus a strong optimization ('pass lang'). Full routing guidance is present.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds value by disclosing the chapter 0/1 equivalence, the truncation behavior, and the exact return fields including truncated and markdown_url. It stops short of describing pagination or rate-limit behavior, keeping it a solid 4 rather than 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-loaded with the purpose, then cleanly segmented into when-to-use, do-not-use, and returns. Every clause earns its place; no filler.

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

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

With no output schema, the description usefully enumerates the return fields and covers the key edge case and the primary alternative. It is nearly complete, with the only gap being undocumented lang/slug parameter semantics.

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 50%; chapter and max_chars are documented, but lang and slug are not. The description adds real meaning for chapter ('0/1 are both accepted for the opening chapter') and implies truncation semantics for max_chars, but says nothing about lang or slug, so it only partially compensates for the coverage 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?

States a specific verb and resource ('Clean Markdown of a single chapter') and positions itself ('the recommended way to put Cyber Library text into an agent context'). It names the sibling it complements (cyberlibrary_get_toc) and the one it is not (cyberlibrary_get_markdown), so an agent can route without opening schemas.

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

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

Explicit 'When to use: after cyberlibrary_get_toc, to read the specific chapter you care about' and 'Do not use: to read an entire book in one shot (use cyberlibrary_get_markdown, but mind the size)'. This names the alternative and the condition that selects it plainly.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the deterministic chunk_id format (lang:slug:chapter:para) and chunk stability, which matter for caching/indexing. It does not discuss rate limits or pagination semantics beyond the schema fields, so a 4 rather than 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-loaded purpose, then labeled When/Do-not/Returns blocks. Dense but every clause carries routing or payload information; nothing is redundant filler.

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

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

No output schema exists, but the description enumerates the return object (lang, slug, title, license, corpus_version, total_chunks, chunk fields), so an agent knows both how to call it and what comes back. Nothing material is missing.

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

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

Schema description coverage is 100%, so limit, start, chapter and max_chars are fully documented in the schema itself. The description adds no parameter-level detail beyond the return payload shape, making the baseline 3 correct.

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 phrase ('Stable paragraph-level chunks for one book') and immediately qualifies it against sibling tools (whole chapters vs. cross-book search). An agent can distinguish it from cyberlibrary_get_chapter and cyberlibrary_fulltext_search without opening either schema.

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

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

Explicit 'When to use' and 'Do not use' sections, each naming the alternative tool that covers the excluded case (cyberlibrary_get_chapter, cyberlibrary_verify_quote/cyberlibrary_fulltext_search). Routing is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context. It does: the return shape {chars_total, chars_returned, truncated, markdown, markdown_url} and the truncation behavior. It omits auth/rate-limit notes, but discloses meaningful behavioral detail beyond annotations.

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

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

Front-loaded with the core purpose, then clearly delineated 'When to use', 'Do not use', and 'Returns' sections. Every sentence is functional with no filler.

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

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

No output schema exists, and the description provides the return shape and truncation semantics. Combined with explicit routing guidance and alternatives, an agent has everything needed to call this correctly versus siblings.

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% - max_chars is documented in the schema while lang and slug are not. The description adds no meaning for lang/slug and only indirectly references truncation via the return fields, so it does not compensate for the coverage 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?

States a specific verb+resource ('whole-book Markdown mirror') with scope (entire book, including metadata header and summary). It distinguishes itself from siblings by naming chapter/toc alternatives and the book-level summary it uniquely provides.

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' clause (complete text needed, after checking chapter_count/word_count via cyberlibrary_book_meta) and explicit 'Do not use' with the alternative (cyberlibrary_get_toc + cyberlibrary_get_chapter, 'far cheaper'). Both the positive and negative conditions are spelled out.

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

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

Annotations already declare readOnly/idempotent/destructive=false, so the safety profile is covered. The description adds genuinely non-annotated context: cost behavior ('single HTML read regardless of chapter count') and a full return shape. It does not mention rate limits or the single-book scope constraint beyond 'one book', so not a 5.

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

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

Front-loads the core definition, then clearly labels When to use / Do not use / Returns. No filler sentences; every clause adds routing or cost information.

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

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

No output schema exists, but the description supplies the return structure in full, and annotations cover the safety profile. The only shortfall is the unexplained required lang/slug parameters, which are likely self-evident but not guaranteed.

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 50%: page/per_page are documented in the schema, but lang and slug carry no schema description. The description names lang/slug only as return fields, not as callable parameters, so it does not compensate for the coverage gap on those two required inputs.

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 ('Table of contents for one book: ordered chapters with their real titles') and immediately distinguishes itself from the prose-reading sibling. An agent can tell it apart from cyberlibrary_get_chapter and book_meta 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: 'right after cyberlibrary_book_meta, to pick which chapter to read', plus a rationale (cheapest way to survey a long book). Explicit when-not: 'to read prose (call cyberlibrary_get_chapter)'. Both the trigger and the alternative are named.

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

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

Annotations already declare readOnly/idempotent/destructive-false, so the safety profile is covered. The description adds real behavioral context beyond that: the pagination model, a concrete scale example (en = 25 pages x 2500 books), and the return shape with books trimmed to `limit`. It stops short of stating ordering of results or what happens when `page` exceeds total_pages, so not a full 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-loaded with the core purpose, then when-to-use, then exclusions, then return shape. Each sentence carries distinct information and there is no filler.

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

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

There is no output schema, so the description carries the return-shape burden and does so explicitly with field names. Combined with annotations covering safety and the schema covering all three params, 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 baseline is 3, but the description adds meaning beyond the schema: the scale example ties `page` and the default 100 `limit` to real pagination behavior, and 'books trimmed to `limit`' clarifies the interaction between limit and the returned count. It still doesn't document zero-based vs 1-based beyond the schema or overflow behavior for `limit`.

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 ('One page of the book catalog for a language') and immediately clarifies the pagination model (large languages paginated, small ones a single shard). It is readily distinguishable from siblings by naming cyberlibrary_fulltext_search and cyberlibrary_book_meta as the not-this alternatives.

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 both a 'When to use' (browse/sample a language, locate a title) and a 'Do not use' with two named alternatives and their selecting conditions. Nothing about routing is left to inference.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral content: what each passage carries (permanent chunk_id, book/chapter/paragraph, citation, license, source URL) and that a packed context string plus citations index are produced. It omits rate limits and any auth requirements, which keeps it short of a 5.

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

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

Purpose is front-loaded, followed by structured 'When to use', 'Do not use' and 'Returns' segments. Every sentence carries distinct information with no filler.

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

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

Although there is no output schema, the description provides a Returns object shape, the usage boundaries, and per-passage payload detail. Combined with full schema coverage and safety annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (baseline 3). The description adds meaning by framing the call around a token budget and packing behavior, contextualizing how budget_tokens/limit/snippet_chars interact, and enumerates the returned fields. Slight value-add over the schema, but no syntax or format detail.

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

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

States a specific verb and resource ('Retrieve ranked passages') plus the distinguishing behavior of packing them into a token budget. It explicitly names the sibling tools it is not (cyberlibrary_verify_quote, cyberlibrary_get_chunks), so an agent can separate it from the crowded cyberlibrary family 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?

Contains an explicit 'When to use' (building a RAG answer needing grounded citations without assembling chunks) and 'Do not use' with named alternatives and their selecting conditions. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's added value is the return contract: answerable/confidence signal, corpus_version, stable chunk IDs, license and source URL fields, and next_actions. That is meaningful context beyond the annotations, though it omits rate limits, corpus scope, or error 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?

Front-loads purpose, then when-to-use, modes, options, and return shape in a clear progression with no fluff. It is dense and the verbose return-field enumeration is justified by the absence of an output schema, though 'auto (default, both)' mildly repeats the schema default.

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 only one required parameter, the description correctly compensates by spelling out the response shape and the confidence/answerable signal. It covers modes, options, and routing, leaving only edge cases like empty results, pagination behavior, or failure modes unaddressed.

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 to the mode enum (schema only says 'Default auto', while the description explains what keyword and semantic actually do). Lang, limit and snippet_chars get no added depth beyond the schema, keeping it from a 5.

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

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

States a specific verb+resource ('Unified CyberLibrary search') and goes further to describe the mechanism (BM25 + neural semantic fusion via RRF) and the output (passages with chunk IDs, citations, confidence). It does not explicitly name the sibling alternatives it overlaps with (cyberlibrary_semantic_search, cyberlibrary_fulltext_search, cyberlibrary_search_passages), so differentiation from those 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?

Explicit 'When to use: first choice when you do not want to decide between keyword and semantic search' gives a clear selection rule, and the mode descriptions (keyword for exact terms/names, semantic for paraphrase/theme) extend that into in-tool routing. No when-NOT-to-use or named sibling fallbacks, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so safety is covered. The description adds value beyond that by disclosing the return payload shape and the downstream contract that lang+slug are prerequisites for other tools. It stops short of describing matching semantics (exact vs fuzzy, ordering, what happens when a language has no matches), so not a 5.

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

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

Front-loaded with purpose, then when-to-use, exclusion, and return shape — a sensible ordering with almost no filler. Minor deduction for the trailing return spec, which is malformed/truncated ('books[']') and uses nested braces that are harder to parse than a plain list.

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 naming the returned fields and envelope keys. Combined with the routing guidance and annotation coverage of the safety profile, an agent can call this correctly; only the garbled return-key syntax and unstated pagination/limit behavior keep it from being fully complete.

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 query, lang and limit are already documented in the schema, giving a baseline of 3. The description reinforces that lang scopes the search to a single language and that its output feeds other tools, but adds no new format, default or edge-case detail for the parameters themselves.

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 catalog by title or author') plus the scoping constraint ('within one language') and enumerates the returned record fields. It is clearly distinguishable from cyberlibrary_fulltext_search and the semantic/passage search siblings because the match target (title/author) is explicit.

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

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

Contains an explicit 'When to use' clause tied to a concrete agent need ('you have a title or author and need the lang+slug that every other tool requires') and an explicit 'Do not use' exclusion naming the correct alternative. This is exactly the routing information an agent needs to choose between overlapping search tools.

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

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

Annotations already declare readOnly/openWorld/idempotent and non-destructive behavior, so the safety profile is covered. The description goes further by disclosing the ranking model (BM25 lexical), the performance tradeoff of passing lang, and the planned neural layer, which is genuinely useful context. It does not discuss result limits or failure modes, keeping it short of a 5.

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

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

Front-loaded with purpose, then when/not-to-use, then parameters, then return shape. The embedded return-schema listing is verbose, but since there is no output schema it earns much of its space; still, it is the longest portion of an otherwise tight definition.

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 fully specifies the return object and its result fields, and the absence of structured output is compensated for. Combined with the usage routing and ranking note, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by advising 'Pass lang when known (faster/more precise)' and framing query as natural-language or keyword. It does not clarify slug/snippet_chars 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?

States a specific verb and resource ('Ranked passage retrieval over the paragraph index (BM25)') and immediately scopes the input mode ('natural-language or keyword query'). It clearly distinguishes itself from the many library siblings by naming the retrieval mechanism and the paragraph-index target.

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' and 'Do not use' clauses, with named alternatives: cyberlibrary_verify_quote for exact quotations and cyberlibrary_get_chunks for whole-book reading. This routes the agent correctly among close siblings with no inference required.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, but the description adds valuable context beyond those annotations: it discloses the BM25 fallback when the embedding service is down and fully describes the return payload. This is a rich behavioral disclosure for a search 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-loaded with the purpose, then clearly labeled sections for when to use, when not to use, fallback behavior, and return shape. Despite including a full return schema inline, every sentence earns its place and the structure is highly scannable.

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

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

Given that there is no output schema, the description supplies the full return object shape. Annotations cover the safety profile, the input schema covers parameters, and the description covers routing and fallback behavior. Nothing material is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents query, lang, and limit. The description adds meaning beyond the schema by explaining that the query should be a natural-language paraphrase or theme, with concrete examples, though it does not elaborate on the lang or limit parameters.

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 ('Semantic passage search over a neural embedding index') and explicitly distinguishes the tool from keyword/BM25 search. It also names sibling alternatives (cyberlibrary_verify_quote, cyberlibrary_get_chunks), so an agent can route correctly without opening other 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' criteria with illustrative paraphrase/theme examples and an explicit 'Do not use' list naming the better sibling for exact quotations and whole-book reads. The alternatives are named with their conditions, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds value by disclosing the return shape ('a flat map of named endpoint URLs plus version and citation guidance'), which no annotation or 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 the purpose, then cleanly segmented into When to use / Do not use / Returns. The endpoint enumeration is long but each item is a distinct capability an agent may want to discover; slight verbosity keeps it from a 5.

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

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

With no parameters, no output schema, and annotations carrying the safety profile, the description covers the essentials: what it returns, when to call it, and when not to. Key names inside the returned map are not specified, but that is a minor gap for a discovery 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No schema-level parameter semantics are needed.

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 ('Discovery endpoints for Cyber Library') and enumerates exactly what it exposes (MCP endpoint, tools list, Server Card, catalog API, OpenAPI, search UI). It is immediately distinguishable from the sibling book-data tools like cyberlibrary_get_chapter or cyberlibrary_search_books.

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 provides both directions: 'When to use: you need a machine-readable entry point or want to know what else this service exposes' and 'Do not use: for book data itself.' The negative guidance routes the agent away from the entire cyberlibrary_* book family without ambiguity.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral detail beyond that: exact substring matching first, then fuzzy matching at a >=90% threshold, plus the returned corpus_version. It omits potential caveats such as rate limits, corpus scope, or what a no-match result implies, keeping 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?

The description is dense and front-loaded: purpose, when to use, when not to use, matching strategy, and return shape follow in logical order. Every sentence adds decision-relevant information with no filler.

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

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

There is no output schema, so the description explicitly lists the return object fields, including verified, match_type, best_score, match details, and corpus_version. Combined with clear usage boundaries and matching behavior, it gives an agent everything needed to invoke and interpret the 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 100%, so lang, slug, limit, and quote are already documented in the input schema. The description adds no further parameter-level semantics such as how lang interacts with matching or what slug values look like. Baseline 3 is appropriate when the schema carries parameter meaning.

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: verify a quotation against the Cyber Library corpus and return the passage, book, chapter, chunk_id, and citation. It also distinguishes itself from sibling tools by naming cyberlibrary_search_books and cyberlibrary_get_chapter as outside its scope. An agent can identify the tool's function 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?

Explicitly states when to use it (before citing, to catch hallucination, to ground a claim) and when not to use it (finding a book by title, reading a chapter), naming the alternatives. The conditions for choosing this tool are directly actionable.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the response envelope including an `errors` field, signalling partial-failure behavior across platforms. It does not mention freshness/latency or rate limits, which would push it to 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 labeled clauses (purpose / when to use / do not use / returns) with zero filler and the purpose front-loaded. Every sentence 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?

No output schema exists, but the description supplies the return shape inline ({platform, count, items:[{title, heat, url, source}], errors}). Combined with the top-level selection guidance and platform coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry the burden — it names the platforms (mapping to the enum) but says nothing about `limit` (range 1-30, default 10) or what `platform: all` aggregates. Partial compensation for two undocumented parameters.

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 ("cross-platform social hot lists") and enumerates the exact platforms covered. An agent can immediately tell this apart from attention_trend and web_search 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?

Explicitly names when to use it ("what people are talking about now, content ideas, trend discovery") and when not to, routing to two named alternatives (attention_trend for search interest over time, web_search for general web search). Nothing is left to inference.

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

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

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.