Hydrafetch

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

The description discloses the key asynchronous behavior beyond what annotations provide: it returns a batch id immediately and requires later polling via batch_status. The readOnlyHint and openWorldHint annotations are not contradicted by any wording.

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 short sentences with no filler. The main action is front-loaded, and the follow-up polling mechanism is placed directly after, giving a clean and efficient structure.

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 a single fully documented parameter, no output schema, and annotations that already cover the safety profile, the description is complete. It covers the essential flow: submit a list, get a batch id, then read via batch_status.

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 fully describes the only parameter ('The URLs to scrape'), so the description adds limited semantic value. The phrase 'you already have' slightly clarifies that URLs are pre-existing rather than discovered, but this is a minor addition.

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 action ('Scrape') on a specific resource ('a list of URLs') and adds the batch scope ('as one job'). It implies a distinction from crawl-style discovery with 'you already have,' but it does not explicitly name alternatives or differentiate from the single-URL 'scrape' 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 clearly signals when to use this tool: when you already have a list of URLs to scrape. It also directs the user to batch_status for retrieving results, which is a concrete usage pointer. It does not explicitly state exclusions or alternative tools, but the context is clear enough.

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?

Annotations already mark the tool as read-only and non-destructive. The description adds the key behavioral trait that the tool returns a crawl id immediately and that results must be retrieved later via crawl_status. This is useful beyond the structured annotations, though it does not cover failure modes or rate limits.

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 filler. It front-loads the core purpose, then covers the return contract and the alternative usage pattern efficiently.

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 strong schema coverage, safety annotations, and no output schema, the description tells the agent what the tool does, what it returns, and how to consume the result. That is sufficient for correct invocation and 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?

Schema description coverage is 100%, so the schema already documents url, limit, and maxDepth. The description adds no parameter-specific meaning beyond framing the job as whole-site crawling, 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?

The description states a specific verb and resource: 'Discover and scrape a whole site as one job.' It also distinguishes itself from the scrape sibling by saying 'Use this instead of calling scrape in a loop,' making the tool's role clear.

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 when-to-use instruction with a named alternative: use this instead of calling scrape in a loop. It also tells the agent where to read results via crawl_status, so the consumption path is clear.

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 declare readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context about ranked results and the extra credit cost of scrapeResults, but does not disclose pagination behavior, query limitations, or the dependency of preferStructure on scrapeResults.

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 filler. It front-loads the core purpose and output format, then adds the optional scraping behavior and cost in a clear, compact way.

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 adequately names the return fields (title, url, snippet). However, it lacks guidance on when to choose this tool over siblings, does not explain how preferStructure relates to scrapeResults, and omits any mention of pagination or result ordering beyond 'ranked'.

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 adds value beyond the schema by explaining that scrapeResults fetches each result as markdown and costs 1 extra credit per page, which is not present in 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 states the tool searches the web and returns ranked results with title, URL, and snippet. It is specific about the resource and output format, though it does not explicitly differentiate itself from sibling tools like images or extract.

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 provides no guidance on when to use this tool versus alternatives such as images, map, extract, or scrape. It mentions the scrapeResults option but does not explain when a user should prefer search over sibling tools.

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

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

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