ContextFetch

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

Beyond readOnlyHint and openWorldHint, the description discloses the search-and-answer process, LLM involvement, citation behavior, fallback querying when pages lack the answer, latency (~2 s), and cost. These are meaningful behavioral and operational details not captured by 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 front-loaded with what the tool returns, then adds routing guidance and cost/speed details. It is dense but every clause carries useful information; the first sentence is long but not padded.

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 sufficiently explains that the return value is a written answer with citations, including how missing information is handled. Combined with the schema's parameter coverage and the cost/latency notes, an agent has enough context 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 the schema already explains both parameters. The description adds cost and timing semantics for the depth option ($0.001 default vs $0.002 standard, ~2 s vs ~10-15 s), which goes beyond the schema's functional 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?

The description states a specific output and process: a finished answer to a question with citations, generated by a deep search plus an LLM over top pages. It distinguishes itself from contextfetch_answer (quotes only) and contextfetch_search (raw sources), so an agent can identify its role without opening the schema.

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

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

It gives explicit when-to-use guidance: use this when you want the answer itself, use contextfetch_answer for quotes, and use contextfetch_search for raw sources. It also explains the depth choice and its trade-off between speed and richer research.

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 declare readOnlyHint and openWorldHint; the description adds the genuinely non-obvious traits: output is strictly extractive (quoted, never generated), the ranking pipeline uses a cross-encoder over the top pages, passages carry [n] citations, and each call costs $0.001. Cost and the extractive-only guarantee are exactly the facts an agent needs before calling.

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

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

Two sentences, zero filler. The core behavior is front-loaded, followed by the usage caveat and pricing compactly in one clause.

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, so the description carries the return-shape burden and does so: passages with [n] citations to their sources. Combined with the cost note and the open-ended-question caveat, an agent has everything needed to decide and invoke.

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 are already documented there ('The question', 'Pages searched for passages (1-10, default 5)'). The description adds no syntax or semantic detail beyond that, 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?

Uses a specific verb+resource pair ('Answer a question with passages quoted verbatim from the web') and explains the mechanism: search, cross-encoder scoring of every passage, return of best passages with [n] citations. The phrase 'never generated' and 'quick factual lookups' separates it from generative siblings like deep_research or research.

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 scopes usage to 'quick factual lookups' and warns that quotes 'may not fully answer an open-ended question', which implies when to reach for a heavier sibling. It stops short of naming the alternative (e.g. deep_research or research), so the agent must infer the routing.

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 a non-read-only, idempotent, open-world mutation. The description adds real context beyond them: prerequisites for success and the hard constraint that the monthly cap cannot be raised above $500 in this tool. It omits what happens to a pending top-up when disabled and what the response looks like, 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?

Three short sentences, front-loaded with the action and mechanism, then prerequisites, then the ceiling constraint. 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 four-parameter mutation with annotations covering the safety profile and no output schema, the description covers purpose, mechanism, prerequisites, and limits. Remaining gaps (error cases, effect of disabling on pending top-ups) are minor.

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 relational semantics the schema lacks — how threshold_usd, amount_usd, and monthly_max_usd interact per billing cycle — plus the $500 ceiling that applies to the cap parameter.

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 ('Turn auto top-up on or off, or change it') and then describes the exact mechanism: threshold breach triggers the saved card to add amount_usd up to monthly_max_usd. Clearly a billing-configuration tool, distinguishable from all sibling search/fetch/research 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?

Provides clear usage context and prerequisites ('Needs an API key and a card saved at checkout'), which tells the agent when the call will fail. It does not name alternatives or exclusions, but no sibling is a real substitute here.

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 flag readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real behavioral context beyond that — the required Bearer auth, that the call is free, that the burn rate is a 7-day average, and that a payment-failure error may be surfaced. Missing only rate-limit or freshness/availability caveats.

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

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

Two compact clauses with no filler: the return payload is front-loaded and every trailing detail (7-day average, conditional last-error, auth/free) carries information an agent needs. Nothing could be deleted without losing meaning.

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 and no output schema, the description does the work of describing the response shape by naming the fields returned, which is exactly what an agent needs to decide whether to call it. A brief note on what the balance object looks like when the key is invalid or unfunded would make it 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The one implicit input, the API key supplied via the Authorization header, is in fact explained in 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?

Specific verb 'Show' plus a precise resource ('the API key's balance') and an explicit enumeration of what comes back: dollar balance, 7-day average daily burn rate, auto top-up settings, and the last auto-reload error. It is clearly not the crawl/search/research siblings, though it overlaps with contextfetch_auto_reload (it reads those settings rather than changing them) without saying so.

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

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

Usage is implied rather than stated: an agent can infer 'call this to check remaining credit or diagnose a failed payment'. The prerequisite is explicit ('Needs an API key (Authorization: Bearer); free'), but there is no guidance on when to prefer this over contextfetch_auto_reload for the top-up portion, nor any note about calling frequency.

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?

With readOnlyHint and openWorldHint already covering safety, the description adds substantial non-obvious context: the cost per page ($0.001/page, $1 per 1,000), the same-site link restriction, and the effect of `query` in pruning to relevant passages. It does not cover authentication or rate limits, but the cost and scoping disclosures are valuable.

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

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

Two dense sentences with the tool's action, scope, output format, and cost front-loaded. Every sentence carries useful 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?

For a read-only crawl tool with 100% schema coverage and no output schema, the description supplies the key missing context: output is Markdown pages, `query` changes the result shape, and cost is per returned page. It does not describe pagination or failure behavior, but enough is present to call the 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 description coverage is 100%, so every parameter is already documented. The description restates the `max_depth` and `limit` caps and explains that `query` ranks and prunes pages, but adds little syntax or meaning beyond what the schema already provides. 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?

The description states a specific verb and resource ('Crawl one website from a start URL') and specifies the output format ('get its pages as Markdown'). It also constrains scope ('same-site links only'), making it easy to distinguish from siblings like extract_url for single pages or map for site structure.

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

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

The description explains what the tool does and how the `query` parameter changes behavior, but it never explicitly says when to choose this over contextfetch_extract_url or contextfetch_map. Usage is implied by the crawl scope rather than stated as a decision rule.

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 readOnlyHint/openWorldHint annotations, it discloses the key trait an agent needs before calling: this is an LLM-free composite that issues many searches and page fetches, and it costs $0.003 per report ($3 per 1,000) — a material budget consideration. It also discloses the report's structure and that every passage is quoted verbatim with [n] citations.

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 capability, followed by cost and the sibling routing sentence. The opening sentence is long and clause-heavy, but every clause carries distinct information (scope, pipeline, output shape, citation format); 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?

For a 3-parameter tool with full schema coverage and no output schema, the description fully compensates by describing the return structure (summary, key facts, sections per sub-topic, sources) and citation format, plus cost and the sibling alternative. An agent has everything needed to decide and invoke correctly.

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

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

With 100% schema description coverage the baseline is 3, but the description adds meaning the schema does not: sub_queries replace the auto-derived sub-topics ('its sub-topics (or your sub_queries)'), clarifying what happens when the parameter is omitted. It does not add anything further on num_results_per_query beyond what the schema already 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: a one-call deep research process that runs the question, its sub-topics and linked pages through searches and returns one cited report with a summary, key facts, per-sub-topic sections and sources. It also explicitly differentiates itself from the sibling contextfetch_research by characterizing that one as a 'quick evidence pack'.

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

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

Gives a clear selection rule: use this for deep multi-page cited research, use contextfetch_research for a quick evidence pack. The alternative is named with the condition that selects it. It stops short of stating exclusions (e.g. simple lookups or when cost matters) or prerequisites, so it is not a full when/when-not 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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description still adds real value by disclosing the output format (clean Markdown, tables preserved) and the scope constraint that the page must be public, which annotations do not convey.

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

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

Two sentences, zero filler, and the primary capability plus output format are front-loaded ahead of the optional-parameter tip. 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?

With no output schema, the description usefully declares the return format (Markdown with tables preserved) and the public-URL constraint, which is most of what an agent needs. It omits failure behavior for non-public or blocked URLs and any page-size or truncation notes.

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 both parameters are already documented, giving a baseline of 3. The description's note that `query` returns only relevant passages restates the schema rather than adding syntax, length limits, or matching behavior.

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 ('Fetch a public web page') plus the output transformation ('clean Markdown with tables preserved'), which separates it from a raw page fetch. However, it never names the closely related siblings (contextfetch_crawl, fetch, contextfetch_search), so the agent must infer the boundary itself.

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 second sentence implies when to use the `query` mode versus fetching the whole page, which is useful implied usage. There is no guidance on when to pick this over contextfetch_crawl, fetch, or contextfetch_search, and no exclusions (e.g., authenticated or JS-rendered pages).

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 (readOnlyHint, openWorldHint), and the description adds two genuinely useful behavioral facts beyond them: results exclude the source domain, and the payload is titles, URLs and top passages rendered as Markdown. That said, it does not mention latency, caching, or result ordering.

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

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

Two sentences, no filler, with the core operation and its key constraint (source domain excluded) front-loaded and the return format appended last. Every clause carries 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?

With readOnly/openWorld annotations supplied and both parameters documented at 100% coverage, the remaining gap is the absence of an output schema; the description compensates by describing the return payload. Only the lack of sibling disambiguation and any note on result freshness keeps it from a 5.

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 interpretive value the schema lacks: it defines what 'similar' means in practice (alternatives, related docs, competing libraries), which directly shapes how an agent chooses the url to pass. It adds nothing on num_results, which the schema already fully documents.

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

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

The description states a specific verb and resource ('Find pages similar to a given URL') and even enumerates the similarity kinds that matter (alternatives, related docs, competing libraries), which separates it conceptually from a general web search. It does not name any sibling tool, so an agent still has to infer the split from contextfetch_search or contextfetch_research, keeping it short of a 5.

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

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

The parenthetical use cases (alternatives, related docs, competing libraries) imply when the tool is appropriate, but there is no explicit when-to-use guidance and no statement of when to prefer one of the many sibling tools (search, research, deep_research) instead. Usage is inferable rather than stated.

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?

With only readOnlyHint=false and openWorldHint=true in annotations, the description carries the load and does so well: it discloses that no signup/payment is required, the resulting balance, the irreversible per-network limit, and how to use the returned key as a Bearer token.

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

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

Two sentences, front-loaded with the outcome and benefit, followed by the constraint and usage instruction. 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?

For a zero-param tool with no output schema, the description covers everything needed: what it returns (the key), how to use it, and the irreversibility constraint that governs whether to call 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?

Zero parameters, so there is nothing to disambiguate and the schema coverage is trivially complete; the description correctly adds no parameter noise.

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 ('Get a free ContextFetch API key') with concrete qualifiers (no signup, no payment, $2.50 starter balance), which is clearly distinguishable from siblings like contextfetch_balance or contextfetch_answer.

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

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

Gives an explicit trigger condition — 'for when the keyless daily limit runs out' — plus a hard eligibility constraint ('one key per network, ever'). It does not name sibling tools or state what to do instead if a key already exists, but the when-to-use context is concrete.

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 genuinely non-schema context: it does not fetch page bodies, it resolves sitemap location via robots.txt with a /sitemap.xml fallback, it is same-site scoped, and it has an explicit price point ($0.001). Missing is any statement about return shape/ordering beyond "URLs" and any rate/limit-per-call caveats, which keeps it off a 5.

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

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

Two sentences, front-loaded with the core action and source resolution, followed by the routing hint and cost. No filler, and the scoping ("same site only", "up to `limit`") is stated inline rather than buried.

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 does cover the essential nature of the return value (a URL list derived from sitemaps plus start-page links) and the cost model. What remains unstated is output ordering/dedup behavior and whether the caller can page beyond the limit, a minor gap for a read-only 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?

Schema description coverage is 100%, so the schema already documents url, limit, exclude_paths, and include_paths including the regex semantics and 1-5,000 bounds. The description only restates the limit cap and says nothing about the include/exclude regex filters, so it adds essentially no meaning 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 and resource ("List a website's URLs"), names the exact sources (robots.txt sitemaps, else /sitemap.xml, plus start-page links), and constrains scope ("same site only, up to `limit`"). It also explicitly situates itself relative to siblings contextfetch_extract_url and contextfetch_crawl.

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 says when to use it ("to find the right pages before contextfetch_extract_url or contextfetch_crawl"), naming the alternatives and the ordering condition that selects this tool. The "without fetching its pages" clause also implies the when-not (you want content, not discovery).

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 past the readOnly/openWorld annotations: discloses the $0.001 per sub-query cost model, that searches run concurrently server-side, that results are deduped by URL, that passages are quoted verbatim with no generated text, and exactly how sub_queries are auto-derived. This is the kind of behavioral detail an agent needs to budget and trust the 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?

Two dense sentences, front-loaded with the core mechanic before cost and parameter guidance. Every clause carries information, though the parenthetical derivation rule is slightly tangled to parse on first read.

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

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

With no output schema, the description still explains the return shape precisely — one Markdown evidence pack with numbered [n] sources and query-pruned verbatim passages. Cost, determinism, and parameter fallbacks are all covered, leaving nothing an agent needs before calling.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds beyond it: it explains what a good `sub_queries` value looks like (distinct angles) and documents the default derivation logic for when it is omitted, which the schema does not state. `num_results_per_query` is left to the schema, hence not 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 concrete verb chain: runs up to 5 concurrent sub-queries, dedupes by URL, cross-encoder ranks, and returns a single Markdown evidence pack. That is far more precise than 'research a question'. It stops short of 5 because it never names siblings (contextfetch_search, contextfetch_deep_research, contextfetch_answer) to say how this differs from them.

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

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

It gives real in-tool guidance: prefer passing your own distinct-angle `sub_queries` for better coverage, and it explains the fallback derivation when omitted. But it never says when to reach for this tool versus contextfetch_search or contextfetch_deep_research, nor when not to use it.

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 and openWorldHint=true, covering the safety and scope profile. The description adds genuine value beyond that by disclosing the return shape (title, URL, pruned passages) and the token-cost behavior, which matters since there is no output schema. It still says nothing about auth, rate limits, or quotas.

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

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

Three tight sentences: capability first, then the token-saving mechanics, then use cases. Nothing wasted and the value proposition is 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?

With no output schema, the description appropriately explains the result shape and pruning behavior, and the rich schema covers all 11 params. It stops short of noting limits like result freshness bounds or per-call cost, but is broadly complete for a search 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?

All 11 parameters have 100% schema description coverage, including enum meanings and date formats, so the schema carries the semantics. The description adds no parameter-level guidance beyond the schema, which is the expected baseline.

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 (search) and resource (the web) plus the differentiator: results come back as LLM-ready Markdown with cross-encoder-pruned passages. However, it never names which sibling it competes with (e.g., contextfetch_answer or contextfetch_crawl), so the agent must infer the distinction itself.

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 clear when-to-use contexts: current events, documentation, APIs, research and fact checking. It offers no exclusions or explicit alternatives, so it doesn't tell the agent when to prefer contextfetch_answer or contextfetch_research instead.

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 and open-world safety, leaving the description to disclose the return payload, which it does by listing {id, title, text, url, metadata}. It does not mention truncation, size limits, or failure modes for an unreachable URL, but the return contract is a meaningful addition beyond 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?

Two sentences, zero filler, with the action and the return shape front-loaded. 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 a one-parameter read tool with annotations covering safety and no output schema, the description supplies the action, the id source, and the return fields. It is nearly complete, only lacking notes on text truncation or error behavior for invalid URLs.

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 single parameter is already fully documented by the schema ('An id from `search` (the page URL)'). The description restates the same fact without adding format or validity detail, so the baseline of 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 (fetch) and resource (full text of a search result identified by its id/URL), and even names the return shape. It is reasonably distinguishable from search and crawl, though it does not explicitly contrast itself with the closely related extract_url sibling.

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

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

The description implies the tool is used for the second step of a search workflow (id comes from `search`), but it gives no explicit when-to-use/when-not guidance and never mentions alternatives like extract_url or crawl that could serve overlapping 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine value beyond them by disclosing the return shape ({results: [{id, title, url}]}) and the chaining contract to `fetch`, which is not in the schema.

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

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

Two short sentences, front-loaded with the core action, then the return shape and next step. No filler or repetition.

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

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

With no output schema, the description usefully supplies the return structure and the follow-up step. Minor gaps remain (result count limits, pagination, whether queries support operators), but the definition is otherwise sufficient for a simple search 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% for the single `query` parameter, so the baseline is 3. The description adds nothing about query syntax or constraints; its mention of `id` pertains to output, not input 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 and resource ('Search the web') and even names the downstream sibling `fetch` for retrieving page text. It does not differentiate itself from the other search-adjacent siblings (deep_research, research, crawl), so it falls short of a 5.

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

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

Usage is implied by 'Search the web' and the description hints at a workflow by telling the agent to pass an id to `fetch`. However, it gives no explicit when-to-use vs when-not guidance and does not distinguish itself from the many sibling research/search tools.

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