Hydrafetch

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely non-redundant behavior: the job runs in the background and returns a batch id immediately rather than results. The per-URL credit cost is a valuable disclosure the annotations don't provide; rate limits or failure behavior are not covered.

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 with zero filler; the core action and async nature are front-loaded, followed by the follow-up tool and 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?

For a one-parameter tool with no output schema, the description covers the return value (batch id), the follow-up mechanism (batch_status), the execution model (background job), and the cost. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter, whose description already says 'The URLs to scrape.' The description adds no syntax, format, or limit detail (e.g. the 25,000 max), so it neither compensates nor misleads — baseline 3 when the schema does the work.

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 ('Scrape a list of URLs') plus the distinguishing scope ('you already have', 'as one background job'), which separates it from single-URL scrape and discovery-oriented crawl. An agent can pick it out 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?

The phrase 'URLs you already have' implicitly excludes URL-discovery cases, and it explicitly routes the caller to batch_status for progress and results. It stops short of naming an alternative tool (e.g. crawl) for the discovery case, so it's clear context rather than a full when/when-not routing 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context: results come back one page at a time, in the original URL submission order, with a nextOffset cursor signaling more pages to fetch.

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 tight sentences with no filler, and the core purpose is front-loaded before the pagination instruction. 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 carries the return-value burden and does so adequately: it names progress, a page of results, ordering, and the nextOffset cursor needed to continue reading. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the relationship between the returned nextOffset and the offset input, which the schema alone ("Position of the first result to return") does 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 (Read) and resource (a batch started with batch), plus exactly what is returned: progress plus one page of results in the order URLs were sent. This clearly separates it from the sibling 'batch' that creates the batch and from crawl_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?

It gives an explicit conditional workflow for pagination: when nextOffset is not null, pass it as offset. It does not, however, state when-not to use it or contrast it with other status tools such as crawl_status, so it stops short of full when/when-not/alternatives 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is handled externally. The description adds that data is derived from a domain and aggregates multiple asset types, but says nothing about caching, rate limits, or whether the domain must be resolvable. Adequate but not rich given annotations cover the core 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?

Two tight sentences with the return contents front-loaded and the usage hint second; every clause earns its place 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?

With no output schema, the description usefully enumerates the returned fields (logos, colours, name, description, social profiles), covering the main completeness burden for a single-param read tool. It stops short of clarifying edge cases (missing brand, unrecognized domain) or overlap with the 'logo'/'styleguide' siblings.

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

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

Schema coverage is 100% and there is only one parameter, so the schema fully documents 'domain' including the URL-tolerance note. The description adds no syntax or format detail beyond what the schema provides, 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?

Names a specific resource (a company's brand) and enumerates the concrete contents it returns (logos for light/dark, colours, name, description, social profiles), which is clearer than a bare verb+noun. However, it does not distinguish itself from the sibling tools 'logo' and 'styleguide', which plausibly overlap, so an agent cannot fully disambiguate from structure alone.

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 gives a use case ('answer what a company is or how it presents itself'), which implies intent, but it names no alternatives and offers no when-not-to-use guidance. Given overlapping siblings like 'logo' and 'styleguide', explicit routing would have been valuable and is absent.

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 openWorldHint=true, readOnlyHint=false, destructiveHint=false. The description adds genuinely new operational context beyond those: the job is asynchronous ('returns a crawl id straight away') and each page consumed costs 1 credit, which tells the agent to budget the crawl. It does not cover failure behavior or rate limits, 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, correctly front-loaded: what it does, how to retrieve output, then the cost constraint. Every sentence carries distinct information and nothing is redundant.

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

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

With no output schema, the description still tells the agent the immediate return is a crawl id and where to follow up (crawl_status), and all three parameters are described. Minor gaps remain around error handling or authentication, but for a straightforward async crawl trigger this is close to complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by tying 'limit' to a concrete consequence (1 credit per page scraped, so set limit to what you need), which gives the agent a reason to tune that parameter rather than just its range.

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

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

States a specific verb and resource ('discover and scrape the pages of a website') plus the mode ('as one background job, following its links from a starting URL'), so the agent knows this is a recursive multi-page scrape. It does not explicitly distinguish itself from the single-page sibling (scrape) or the URL-listing sibling (map), which keeps it just 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?

Implies when to use it (whole-site coverage via link following) and points to crawl_status for reading progress and results. However it never states when NOT to use it or names a competing alternative (scrape, map, batch) explicitly, leaving the usage boundary to inference.

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

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

Annotations already establish readOnly, non-destructive, open-world. The description adds behavior annotations do not cover: that output is one page of results plus progress, and that pagination continues via nextOffset fed back as offset. This is useful return/pagination context absent from structured fields.

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

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

Two sentences, no waste, and the core read/pagination intent is front-loaded before the continuation instruction.

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

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

With no output schema, the description correctly fills the gap by naming the return payload (progress, one page of results, nextOffset) and how to consume it. Complete enough to call correctly, with only minor detail about default limits left to the schema.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema by explaining that offset should carry the nextOffset value from a prior response, and that this drives paged reading.

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 (Read) and resource (a crawl started with crawl) plus what is returned: progress and one page of results. It ties itself to the sibling crawl tool for provenance, though it does not explicitly differentiate itself from 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?

Gives clear context (use after starting a crawl with crawl) and an explicit continuation rule: when nextOffset is not null, pass it as offset. No exclusion or when-not-to-use guidance, but the usage condition 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that extraction is model-driven and constrainable by schema or prompt, but says nothing about cost, latency, rate limits, or failure behavior when a schema cannot be satisfied.

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 followed immediately by the selection criterion. No filler or restated field names.

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

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

No output schema exists, but the description explains the return shape (JSON conforming to a provided schema, or prompt-derived) and that multiple URLs can be processed. Adequate for an agent to call correctly; only an edge case like schema-vs-prompt precedence is unaddressed.

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

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

Schema description coverage is 100%, so the six parameters are already documented in the schema. The description mentions the schema/prompt duality but adds no syntax, precedence, or interaction guidance (e.g., whether prompt and schema can be combined) beyond the structured fields.

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 ('Pull specific fields out of one or more pages as JSON') and the two shaping mechanisms (JSON schema or prompt). It implicitly distinguishes itself from the scrape sibling by contrasting with 'the whole page text', though it never names the alternative tool.

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 when-to-use condition with concrete examples ('prices, names or dates rather than the whole page text'), which effectively routes the agent away from scrape/crawl for targeted value retrieval. No explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations already declare 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds genuinely non-obvious behavioral context beyond that: the relative cost ('a fifth as much') and the shape of the result ('one asset instead of the whole record'). It does not discuss caching, auth, or rate limits, keeping it short of a 5.

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

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

Two sentences with no filler. The output form is front-loaded in the appositive, and the routing rule against 'brand' follows immediately, so 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 characterizes the return value as a single embeddable image URL, which is the key thing an agent needs. It omits error behavior and whether the URL is permanent or signed, so it falls just short of fully complete for a simple 3-param read 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% and both enums are fully explained in the schema, so the baseline is 3 per the rubric. The phrase 'chosen for the background you name' loosely reinforces the theme parameter's role, but adds no syntax, defaults, or constraints beyond what the schema already 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 names a specific resource (a company's logo) and the concrete form it takes (a directly embeddable image URL), which is more precise than the tool name 'logo' alone. It also explicitly differentiates itself from the sibling 'brand' tool, so an agent can select correctly without opening schemas.

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

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

It states exactly when to prefer this tool over the sibling: 'Use this rather than brand when the mark is all you need,' and backs it with two concrete selection criteria (cost and payload size). This is an explicit when-to-use and when-to-use-alternative 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 readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds substantive behavior beyond that: discovery is via sitemap and links only, with no content fetching, which tells the agent the operation is lightweight and non-rendering. It omits rate limits and output shape details.

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 tight sentences; the purpose and its scope constraint are front-loaded and the second sentence handles usage. Zero wasted words.

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

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

There is no output schema, so the description responsibly states the return is a list of URLs. Combined with full schema coverage and covering annotations, it is nearly complete, though it doesn't describe pagination/limit interaction or ordering of results.

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

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

Schema coverage is 100% and both params (url, limit) are documented in the schema itself, including the 1-5000 range. The description adds no syntax, format, or constraint detail beyond the schema, 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 (list) and resource (URLs on a website) and immediately clarifies the mechanism (sitemap and links) and the negative scope ('without fetching their content'). This contrasts cleanly with siblings like scrape and crawl that do fetch content.

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

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

Gives a concrete when-to-use: 'see which pages exist before choosing which to scrape,' which effectively signals the scrape alternative and a discovery-first workflow. No explicit exclusions or edge cases (e.g., when to prefer search or crawl), so not a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful context about the return shape (main content as clean markdown, optional HTML/links/structured data) that goes beyond the annotations. It does not mention rate limits, auth needs, or failure behavior, so it falls short of a 5.

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

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

Three short sentences, front-loaded with the core purpose and output, followed by usage and routing. Every sentence earns its place with zero filler.

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

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

There is no output schema, so the description reasonably compensates by describing the return (clean markdown plus optional HTML/links/structured data) and the routing context for a three-sibling group. Pagination, errors and auth are not addressed, but for a simple single-page read tool this is close to complete.

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

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

Schema description coverage is 100%, so the schema already documents url, formats and preferStructure thoroughly, including the 'structure came back plain' retry hint. The description's 'optional HTML, links or structured data' broadly restates the formats enum without adding syntax or defaults beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (fetch), a bounded resource (one web page), and the primary output (main content as clean markdown) plus optional variants. It explicitly distinguishes itself from crawl (many pages) and batch (list of URLs), so the agent can differentiate without opening schemas.

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

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

Gives explicit selection criteria: 'Use it to read a page whose URL you already have,' then names the two sibling alternatives crawl and batch with the conditions that select them (many pages of one site, list of URLs). Nothing is left to inference.

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

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

Annotations already 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.