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 real behavioral value beyond that by describing the response shape per URL type (language-tagged code blocks, ASCII trees, top solutions/comments, changed-file lists), which sets agent expectations. It omits auth or rate-limit 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-loaded with the verb and resource scope, then a routing sentence with no filler. The content-type list is dense but each item earns its place by clarifying a distinct URL pattern; only the parenthetical detail is slightly heavy for a one-sentence preamble.

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

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

With no output schema, the description usefully sketches return formats per URL type, and annotations cover the safety profile. An agent has enough to select and call the tool; missing only edge-case guidance (private repos/auth, invalid URLs, rate limits).

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% for the single required 'url' parameter, so the description carries the burden — and it does, by spelling out the accepted URL patterns (/blob/:branch/:path, /tree/:branch/:path, /issues/:number, /pull/:number). That meaningfully compensates, though it never states that the input is a full GitHub/Gitee URL versus a relative path.

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) and enumerates exactly what resource types it retrieves: README, source files, directory trees, Issues, and Pull Requests, with the URL shape for each. It also explicitly differentiates itself from the sibling fetchWebContent, so an agent can route without opening either schema.

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

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

Provides a clear exclusion and named alternative: 'For generic web pages, use fetchWebContent.' That resolves the most likely ambiguity (this vs. the generic fetcher). It gives no guidance for the other siblings (search, queryDocs), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered; the description then adds substantive behavior beyond that: anti-bot bypass, promotional-noise and watermark removal, code-block language preservation, GFM table retention, markdown default, batch concurrency of 1-3 sharing the maxChars budget, and the truncated/toc/startIndex paging loop. No claim contradicts 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-loads purpose before the feature list, and every clause carries a distinct fact (extraction behavior, format default, focus, batch, truncation recovery) with no filler. It is densely packed into a single run-on paragraph, which slightly hurts scannability, keeping it off 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 9 params, 0 required, 56% schema coverage and no output schema, the description covers most of what an agent needs to call it correctly, including the truncation-recovery loop and reference to the toc response field. The gaps are the unmentioned readability/includeLinks toggles and the maxChars budget semantics, which are never explained in prose.

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 56%, so the description must compensate and does for several params: format default ('markdown' when raw is false), focus targeting (~5000-char window), batch urls (1-3 concurrent, comparing search results), and startIndex paging via nextStartIndex. It leaves readability, includeLinks, and maxChars (only a default is given in schema) unexplained, so coverage remains partial rather than complete.

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) and resource (high-quality readable content) scoped to 'any public HTTP(S) URL', enumerating content classes (web pages, technical docs, Markdown, articles like CSDN/Juejin/WeChat/Stack Overflow). The 'any public HTTP(S) URL' scope implicitly distinguishes it from fetchGithubReadme and from queryDocs/search, so an agent can route correctly 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 concrete conditional guidance: use focus='keyword' for chapter targeting, batch urls for 1-3 concurrent fetches, and when truncated=true inspect toc or pass nextStartIndex as startIndex. It never names when NOT to use this tool versus fetchGithubReadme/queryDocs, so it stops short of a full when/when-not/alternatives statement.

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 openWorld, so the safety profile is covered. The description adds one genuinely useful behavioral fact -- the library argument auto-resolves to the canonical library -- but 'Direct, reliable, no proxy needed' is unverifiable marketing copy rather than disclosure, and no rate/scope limits are mentioned.

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 critical routing cue 'PREFERRED' is correctly front-loaded, but the sentence is overloaded and ends with throwaway promotional clauses ('Direct, reliable, no proxy needed') that consume space without informing invocation.

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 query tool with no output schema, the description adequately conveys what comes back (documentation and code snippets) and how to supply a library. Annotations carry the safety profile and the schema carries parameter detail, so only minor gaps (result format, snippet ordering) remain.

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

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

Schema description coverage is 100%, so all four parameters (query, library, libraryId, limit) are already documented with formats and defaults, making 3 the baseline. The description restates the package-name-vs-ID input convention and the canonical resolution behavior, adding marginal value but no syntax beyond the schema.

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

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

States a specific verb+resource: retrieving up-to-date, version-specific official docs and code snippets for libraries/frameworks, with concrete examples ('next.js', '/vercel/next.js'). The opening 'PREFERRED for official documentation' loosely differentiates it from the generic siblings (search, fetchWebContent, fetchGithubReadme), though it never names them directly.

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

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

The word 'PREFERRED' implies this should be chosen over generic web tools for documentation, which is useful implied guidance. However, there is no explicit when-not condition, no stated prerequisites, and no direct comparison to search or fetchWebContent, leaving the agent to infer the boundary.

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, so the safety profile is covered; the description adds operational context the annotations do not carry — the proxy requirement for overseas engines, the cached-response signal, and the deadline cost of raising minResults. It stops short of return-format or rate-limit detail, but the annotation bar is low and real value is added.

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

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

Purpose and the query/queries requirement are front-loaded, and the engine-routing sentences each carry distinct, actionable information rather than filler. It is dense and slightly run-on, but nearly every clause earns its place.

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

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

For an 8-parameter, no-output-schema tool this is largely complete: query vs queries, engine selection, searchMode, and the cached-return behavior are covered. fetchTop, verbose, limit, and minResults are left to the schema, which is acceptable given high schema coverage.

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

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

Schema coverage is 88%, so parameters are already documented (baseline 3). The description goes beyond the schema by explaining searchMode semantics ('omit/auto = server SEARCH_MODE; request/playwright force that mode') and by mapping engine choices to query intent, which adds meaning the enum and engine list alone do not convey.

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 web across multiple engines') with an immediate differentiator ('no API key required'). It also routes official-doc lookups to the sibling queryDocs, so an agent can separate this multi-engine search from the fetch* siblings 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?

Gives explicit when-to-use guidance keyed to intent: Chinese queries to baidu/sogou/csdn/juejin, bug lookups to github, Q&A to stackoverflow, papers to arxiv, and official library docs to queryDocs instead. It even names the alternative tool and the selecting condition, leaving little to inference.

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