Hydrafetch

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

The description transparently states that the tool returns a batch ID immediately rather than the scrape results, which is a key behavioral aspect beyond the read-only/non-destructive annotations. It doesn't mention any unexpected side effects, aligning with 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 concise sentences that pack in the core purpose, usage, and asynchronous behavior without any fluff or redundancy. Perfectly structured for quick comprehension.

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

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

Given the tool's low complexity (one parameter, no output schema, clear annotations), the description is complete. It covers what the tool does, what input is expected, and what output to expect, and it appropriately references a related tool (batch_status) for follow-up.

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 schema already fully describes the 'urls' parameter, and the description adds only minor context ('a list', 'you already have'). Since the schema coverage is 100%, the baseline is 3, and the description does not meaningfully extend parameter understanding.

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

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

The description clearly states the tool's purpose: to scrape a list of URLs as a single batch job. It distinguishes itself from single-URL scraping by emphasizing 'list' and 'one job'.

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

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

It provides concrete usage guidance by specifying that the URLs should already be known ('you already have') and by directing the user to check batch_status for the result, implying an asynchronous workflow. This effectively tells the user when and how to use the tool.

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 destructiveHint=false, so the safety profile is covered. The description adds that the call returns current progress and results-so-far, but gives no detail on output shape, pagination, or polling 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?

A single front-loaded sentence conveys the operation, the object, and the key output without filler. Every phrase 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-only status tool with a simple schema, the description covers the essential return value: progress and results so far. It does not enumerate output fields, but the complexity is low and no output schema exists, so this is sufficient.

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 single batchId parameter already contains the description 'The id returned by batch.' The tool description adds no additional parameter semantics beyond what the schema already provides.

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 names a specific action (read) and a specific resource (a batch started by the batch tool), and clarifies that it reports progress and partial results. This clearly differentiates it from the sibling tool 'batch', which starts batches.

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 clearly ties usage to batches created by the 'batch' tool, so an agent knows when to call it. It does not explicitly mention alternatives like 'crawl_status' or state when not to use it, so it stops short of full 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 declare this as read-only, non-destructive, and open-world, so the description only needs to add behavioral detail beyond that. It does so by enumerating the returned brand elements and framing the output as a semantic answer rather than a raw dump. No contradictions with annotations are present.

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 with no filler: the first lists the tool's output scope, and the second provides a concise comparative value statement. The key concept 'brand' appears immediately, making the description easy to parse.

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-only tool, the description sufficiently conveys what the caller gets and why it is useful, while annotations cover the safety profile. It does not specify output format or failure behavior, but with no output schema these are not critical gaps for this simple 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 input schema already documents the only parameter thoroughly, including an example and the note that a full URL works. The description only repeats the notion of 'domain' without adding new semantics, so a baseline score of 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 identifies the resource (a company domain) and the concrete returned attributes (logos, colours, name, description, socials), making the tool's purpose clear. It lacks an explicit verb like 'retrieve' and does not directly distinguish itself from the sibling 'logo' tool, but the 'company's brand' framing is specific enough.

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 phrase 'Answers what is this company far better than a raw page dump' implies using this tool when the goal is brand/company identity rather than raw scraping or screenshots. However, it never explicitly states when to use this tool versus the eight sibling tools or provides any exclusion criteria.

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 reveals that the call returns immediately with a crawl id and that results must be polled via crawl_status, which is useful behavioral detail. The read-only, non-destructive annotations already cover side-effect safety, so no additional disclosure is needed.

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 two sentences and every part is functional: purpose, return behavior, and guidance on related tooling. No redundant or vague 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 states the immediate return value and names crawl_status for polling, giving the agent the necessary next step. Sibling context and annotations fill the remaining operational context.

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 schema already provides 100% descriptive coverage for url, limit, and maxDepth. The description does not add extra parameter-level semantics beyond what the schema states, so it stays at the baseline for a fully described 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?

Clearly identifies crawl as a site-wide discovery and scraping job, distinguishes it from page-level scraping, and specifies it returns a crawl id. The description is unambiguous about the tool's core function.

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 advises using this tool instead of calling scrape in a loop and points to crawl_status for reading results. This gives the agent clear guidance on when to choose this tool over its sibling.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail about what the call returns: progress and scraped pages. No contradiction with 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 a single, front-loaded sentence with no filler. It efficiently communicates the action, the target resource, and the key output 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?

For a simple single-parameter, read-only status tool, the description is sufficient: it names the input, the purpose, and the high-level output. It could mention specific status fields or edge cases, but this is not essential for correct invocation.

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 crawlId is already documented as 'The id returned by crawl.' The description does not need to add parameter-level meaning, so a baseline of 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 ('Read') and resource ('a crawl'), and clearly ties it to the crawl operation by saying 'started with crawl'. This distinguishes it from siblings like crawl, scrape, and batch_status.

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 after starting a crawl, which gives clear context for when to call it. It does not explicitly exclude alternatives like batch_status, but the reference to 'a crawl started with crawl' is enough to route an agent correctly.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds mild behavioral context by noting it works across multiple URLs and supports two specification modes, but it does not disclose output format, error behavior, rate limits, or access requirements.

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 a single, tight sentence with no filler. It front-loads the core action and object ('Pull typed structured data') and includes the key invocation alternatives, earning its place without redundancy.

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 four parameters, no output schema, and nested objects, the description is minimally adequate but leaves room for more: it does not clarify what the returned structured data looks like, how `preferStructure` affects behavior, or how to choose between `schema` and `prompt`. The parameter schema compensates for parameter detail, but the description itself is thin.

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 parameters are already documented in the input schema. The description adds only the high-level idea that extraction can be driven by a JSON schema or a natural-language prompt, matching the `schema` and `prompt` parameters, but it does not add meaning beyond what the schema already provides.

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 ('Pull') and resource ('typed structured data from one or more URLs') and names the two modes of invocation: JSON schema or prompt. This makes the tool's purpose clear and implicitly distinguishes it from sibling tools like `scrape`, though it never explicitly names an alternative.

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 when to use this tool: when structured, typed data is needed from URLs, specified either by schema or natural-language prompt. However, it provides no explicit guidance about when not to use it, no mention of alternatives among siblings, and no clarification of when to prefer `schema` over `prompt`.

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 this tool read-only and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond the annotations: it does not render the page, and it returns source images with metadata. This gives the agent a clearer mental model of what invocation will and will not do.

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 two sentences with no wasted words. The core action is front-loaded, and the comparison to screenshot is placed second where it helps decision-making without bloating the description.

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-only tool with no output schema, the description is complete enough. It explains what the tool returns, how invocation behaves, and how it differs from a likely sibling. Nothing an agent needs to select or call this tool 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 schema already documents the single url parameter with 100% coverage, so heavy description compensation is unnecessary. The description reinforces that the URL identifies a page to harvest images from, but it adds no new parameter-level detail such as formats, defaults, or constraints. 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 ('Harvest') and resource ('a page's images with their metadata'), and explicitly distinguishes itself from a screenshot by noting it returns source images rather than a rendered picture. This makes the tool's purpose unmistakable and differentiates it from the sibling tool screenshot.

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 gives clear guidance on when this tool is preferable to a screenshot: it is cheaper and returns source images rather than a visual representation. However, it does not explicitly mention when not to use it or name other alternatives among the siblings, so some selection context is left implied.

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 establish readOnly and non-destructive behavior. The description adds useful behavioral context: the result is a directly embeddable image URL, the logo is selected for the named background, and only one asset is returned rather than a full record. This goes beyond the annotation baseline without contradicting 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?

Two sentences with no filler. The first sentence states the core value and output form; the second delivers the usage decision and cost/benefit comparison. 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 simple read-only tool with fully documented parameters and helpful annotations, the description covers what an agent needs: the output type, the background-dependent behavior, and the distinction from the closely related sibling. The absence of an output schema is acceptable because the description names the return format directly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds modest contextual meaning by mentioning 'background you name' (echoing theme) and 'mark' (echoing icon vs full logotype), but it does not materially expand parameter understanding 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?

The description clearly identifies the tool's output as a company logo image URL and ties it to a background choice. It also explicitly contrasts with the sibling brand tool ('Use this rather than brand'), so an agent can distinguish it without inspecting 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?

The description gives explicit selection guidance: use it instead of brand when only the mark is needed, and cites concrete benefits (lower cost, single asset returned). This is actionable and names the alternative directly.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds a meaningful behavioral detail: the tool uses sitemaps and links to discover URLs, and it does not scrape content. This clarifies the method and scope, going beyond what annotations state.

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 a single, tightly packed sentence that delivers the core purpose and a key constraint ('without scraping them') up front. There is no filler or redundancy; every word 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 simple enumeration tool with two parameters and no output schema, the description is adequately complete. It specifies the input (URL), the output concept (URLs), and the discovery method. The only minor gap is that it does not describe the exact output format (e.g., list vs. array), but this is not critical for calling 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% (both 'url' and 'limit' have descriptions). The tool description repeats some schema info ('from its sitemap and links') but adds no syntax, format, or edge-case details beyond what the schema already provides. Baseline 3 is appropriate given full schema coverage.

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 uses a specific verb ('Enumerate') with a clear resource ('a site's URLs') and method ('from its sitemap and links'). It explicitly distinguishes itself from scraping ('without scraping them'), which differentiates it from the sibling 'scrape' tool. This is a precise and unambiguous statement of the tool's function.

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 phrase 'without scraping them' implies the tool is for URL enumeration rather than content extraction, but it does not explicitly name alternatives or state when to prefer this tool over siblings like 'scrape' or 'extract'. The guidance is implied rather than direct, leaving some 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 decare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds a little context by stating the output is 'clean, LLM-ready markdown and structured data,' but it does not disclose behaviors like rate limits, failure modes, or authentication needs. Since annotations cover the main safety concerns, a 3 is appropriate; the description adds minimal extra 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?

The description is a single, clear sentence with zero filler. It front-loads the core value proposition (URL to markdown/structured data) and does not bury important details. This is appropriately concise for a tool with a straightforward purpose.

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

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

Given the tool has 3 parameters, no output schema, and annotations that define safety, the description is minimally sufficient. It tells the agent what the tool does, but it does not mention that multiple output formats can be requested or that there is a preferStructure option — though those are documented in the schema. With no output schema, a sentence hinting at available output types (beyond 'markdown and structured data') would strengthen completeness, but it is not critically incomplete.

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% — all three parameters (url, formats, preferStructure) have descriptive text in the schema itself. The description does not elaborate on any parameter or add syntax or format details beyond the schema. With full schema coverage, the baseline is 3, and the description adds no additional semantic value.

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

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

The description clearly states a verb ('Turn') and a specific resource (a URL) producing markdown and structured data. It is not a tautology and gives a concrete outcome. However, it does not explicitly differentiate itself from sibling tools like 'extract' or 'search,' which likely have overlapping purposes, so it misses the top score for sibling distinction.

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 gives no guidance on when to use this tool versus its siblings (brand, extract, images, logo, map, screenshot, search, styleguide). It does not mention scenarios, exclusions, or alternatives. With several closely related tools available, this is a significant gap for correct selection.

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 mark the tool read-only and non-destructive. The description adds useful behavioral context: it launches a real browser (implying JavaScript execution) and returns a publicly accessible URL. Caching and freshness behavior are left to the schema's maxAge documentation, which is acceptable given the annotation coverage.

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-load the action and output, then provide the usage context. Every sentence earns its place, and there is no repetition of schema or annotation content.

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 rendering tool, the description covers what it produces, how it produces it, and when to use it. With no output schema, mentioning the PNG and public URL return shape is valuable, and the rich input schema covers the parameters.

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%, with detailed parameter explanations covering defaults, units, overrides, and cache semantics. The description itself adds no parameter-level meaning, but it does not need to because the schema carries that burden.

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: render a page in a real browser, capture a PNG, and return a public URL. It also distinguishes itself from text-oriented siblings by contrasting visual appearance ('what the page looks like') with content ('what it says').

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 a clear decision rule: use when the question is visual rather than textual. This helps an agent choose it over extract/scrape-style tools, but it does not explicitly name alternatives or state when not to use it, so it falls just 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 establish read-only, open-world, non-destructive behavior, and the description adds useful context: results are ranked, each includes title/url/snippet, and enabling scrapeResults fetches markdown at an extra credit cost. No contradiction with 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 with the core function and return format front-loaded, followed by an efficient statement of the optional scrape behavior and its cost. 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?

With no output schema, the description usefully specifies the return fields and the markdown variant. It does not mention pagination or result limits, but the schema covers parameters and annotations cover safety, making the tool adequately callable.

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 baseline is 3. The description independently clarifies scrapeResults's markdown behavior and cost, but it does not add meaning for limit, query, or preferStructure beyond what the schema already provides.

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 names the return payload (ranked results with title, url, snippet). It does not explicitly contrast with sibling tools like scrape or extract, but the core purpose is unambiguous.

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 no guidance on when to choose search over its many siblings such as scrape, extract, or crawl. The only usage instruction is the conditional scrapeResults note, which addresses parameter behavior rather than tool selection.

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 mark readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds value by explaining that values defined in CSS variables are returned resolved to the hex actually painted, and that it runs in a real browser, which are non-obvious behavioral details. It doesn't go into rate limits or auth, but for a read-only tool this is solid.

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, dense with information, no fluff. The first sentence states what it does and what it returns; the second clarifies an important technical detail about CSS variables. Every word 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 read-only inspection tool with one parameter, this is complete. It sets expectations about the output (design tokens), the environment (real browser), and the edge case (CSS variables resolved). Nothing critical is missing for an agent to decide 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?

Schema covers the single 'domain' parameter well (100% coverage). The description reinforces that it accepts a domain like 'stripe.com' and a full URL also works, which adds a bit beyond the schema's example. It could be argued to be a 3, but since there's only one param and the description disambiguates the input format, it edges to a 4.

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

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

The description clearly states it reads a site's design system from computed styles in a browser, and goes beyond a generic label by itemizing what is returned: role colors with contrast ratios, type scale, corner radius, and button styling. It differentiates itself from siblings like 'screenshot' or 'scrape' by specifying it's about design tokens even though those siblings aren't named, the distinctive focus on computed CSS variables makes it stand out.

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's clear the tool is for inspecting a site's design system, not for taking a screenshot or extracting content. It mentions it runs in a real browser and resolves CSS variables, implying it's for accurate read-only style inspection. However, it doesn't explicitly state when not to use it, like when a simple screenshot suffices, nor name an alternative sibling like 'extract' for data extraction.

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