URLpipe

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

Annotations already note idempotency and non-read-only status; the description adds valuable behavioral context beyond that: it costs 1 credit regardless of options, it runs JavaScript and loads web fonts/images, and it renders exactly like a browser. It also discloses that page_options affect downstream artifacts (ads and banners removed from html, markdown, and summaries). 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 front-loaded with the core action, then purpose, then parameter summaries, with no redundant filler. Every sentence earns its place: the first identifies the endpoint and behavior, the second scopes usage, and the third organizes the nested option groups. It is structured for quick scanning.

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 complex 10-parameter tool with nested objects and no output schema, the description covers the essential behavioral context: what is captured, rendering fidelity, pricing, and how the two main option groups affect the result. It does not need to explain return values because the schema already documents sync/async behavior, and annotations cover idempotency. Slightly more could be said about error cases, but this is adequate.

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 fully documents all 10 parameters. The description adds useful grouping and intent—'screenshot_options size it... encode it... restyle it' and 'page_options wait for the page and take ads and cookie banners out of it'—but these are summaries, not new parameter semantics. This meets the baseline 3 without exceeding it.

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 opens with a specific verb and resource: it 'Captures the whole rendered page as a PNG', and clarifies rendering fidelity ('JavaScript executed, web fonts and images included, exactly as a browser would draw it'). It also distinguishes itself from read-oriented siblings by saying 'Use it to see a page rather than read it', making the tool's purpose unmistakable.

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 use cases ('layout, visual regressions, link previews, or checking what an anti-bot page actually showed us') and sets a clear rule of thumb: use it to see rather than read a page. It stops short of naming specific sibling tools or stating when not to use it, but the 'rather than read' contrast implicitly routes text-extraction tasks elsewhere.

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

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

Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=true), so the description carries a lighter burden. It adds meaningful context beyond annotations: the cost ('1 credit'), the fact that it loads the page in headless Chrome, and that capture happens only 'during load'. No contradictions exist 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?

Three sentences with zero filler: behavior, cost, and the use-case heuristic. The most decision-relevant fact (what it returns) is front-loaded, and the usage signal is at the end as a natural closer. 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?

The tool is complex (9 params, nested page_options, async sync flow, no output schema), but the 100%-covered schema handles parameter semantics and the get_result sibling covers the async workflow. The description establishes purpose, cost, and scope well; the only notable gap is that the result format is never described, which would be valuable since no output schema exists.

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 fully documents all 9 parameters including sync, max_age, residential, and page_options; the baseline of 3 applies. The tool description adds no per-parameter detail, though its '1 credit' cost line pairs with the schema's residential-surcharge note. There is no coverage gap for the description to compensate for.

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 verb and resource ('Exposes POST /console', 'capture console errors') and states precisely what is captured: console.error, console.warn, uncaught exceptions, and unhandled promise rejections. It also explicitly excludes console.log, which prevents one common class of mis-selection. The 'What you would open DevTools for' heuristic clearly distinguishes this tool from content-extraction siblings like fetch_html and scrape_url.

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 a clear when-to-use signal: broken third-party scripts and client-side errors that cannot be reproduced locally. It does not name sibling alternatives explicitly or state when NOT to use it (e.g., use lighthouse_audit for performance, fetch_html for markup), so the routing is implied rather than fully specified. The 'not console.log' exclusion adds useful negative 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?

The description reveals the non-obvious cost (15 credits), the output's nature (model-ranked rather than frequency-based), and the practical consequence that fetch_markdown is cheaper if the agent will do its own reasoning. These go beyond the annotations, which only indicate idempotency and non-read-only behavior; there is no contradiction with readOnlyHint=false.

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, front-loaded sentences: endpoint, output/quality, cost, and the decision-relevant comparison. Every sentence adds value and no space is wasted on repeating schema 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 9-parameter tool with no output schema, the description covers the crucial selection facts: what the result looks like, how much it costs, and when to use a cheaper sibling. The full parameter details live in the schema, so nothing essential to correct invocation is missing, though a bit more detail on the result structure would have been useful.

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

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

Schema description coverage is 100%, so every parameter already carries a meaningful description. The tool description adds no parameter-specific semantics beyond the schema, which is acceptable and earns the baseline for high 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 names the exact endpoint (POST /keywords) and the concrete output: 5–15 terms/phrases best representing the page, ordered by relevance. It also distinguishes the tool from siblings by noting that the ranking comes from a language model, not raw frequency, and by referencing fetch_markdown and summarize_page.

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

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

It gives explicit guidance for a key alternative: if the agent will reason over the content itself, fetch_markdown at 1 credit is the better choice, while extract_keywords is positioned as the way to get a pre-digested keyword list. It does not, however, spell out when to pick extract_keywords over summarize_page or extract_metadata, so the routing guidance is strong but not exhaustive.

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 adds behavioral context beyond the annotations: the page is rendered first so JavaScript-injected values are included, the call costs 5 credits, and results are reconciled rather than raw. It does not contradict annotations, and while it does not detail async behavior, the schema's sync parameter parameter already covers that.

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 tight and front-loaded: it opens with the endpoint and core purpose, then adds cost and alternative guidance in a short second paragraph. Every sentence contributes either behavioral context or usage direction, with 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?

Despite having no output schema, the description enumerates the returned fields (title, description, language, main image, favicon, author, publication date, feed), which is the key missing piece. Combined with the fully documented input schema and clear pricing/rendering notes, an agent has enough to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the schema and the description does not need to repeat them. The description adds pricing and rendering context but no additional per-parameter meaning, matching the baseline for fully covered schemas.

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-resource pair ('Exposes POST /meta') and explains what the tool produces: reconciled Open Graph, Twitter card, and page metadata into a clean object. It also distinguishes itself from siblings by saying it is 'not a dump of its meta tags' and points to the cheaper Markdown 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?

It gives explicit guidance on when to use this tool vs alternatives: use it for reconciled page metadata, not raw meta tags; if only the title is needed, the Markdown version costs 1 credit instead of 5. This directly routes an agent to the right sibling 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 cover idempotency, openness, and non-destructiveness. The description adds meaningful behavioral context beyond that: JavaScript execution, redirect following, the 'DOM a real browser sees' distinction, and the 1-credit cost. This helps the agent set expectations without contradicting any annotation.

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 paragraphs, front-loaded with endpoint and core behavior, then usage guidance and a cost comparison. Every sentence earns its place; there is no repetition of schema content or filler.

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

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

For a tool with 9 parameters, nested options, async behavior, and no output schema, the description clearly states the return value (rendered HTML) and cost model while the schema covers parameter mechanics. It could add a note about the async/token flow, but the sync parameter description already handles that, so nothing essential is missing for selection and 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%, so the baseline is 3: the schema already documents all 9 parameters thoroughly, including nested page_options fields. The description adds no parameter-level detail, but it does not need to because the schema carries that burden completely.

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: 'Exposes POST /html. Returns the page's HTML after JavaScript has run and redirects have been followed.' It also distinguishes itself from plain curl and from fetch_markdown, so an agent can readily tell what this tool uniquely produces.

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

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

Gives explicit when-to-use guidance: 'Use it when you need the markup itself: a specific attribute, a script tag, a structured-data block.' It also names the alternative for content reading: 'If you want to read the page's content, fetch_markdown costs the same and returns a fraction of the text.' This is clear routing to the right 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 include readOnlyHint=false (no read-only), openWorldHint=true, idempotentHint=true, destructiveHint=false, but do not cover the rendering process or cost. The description discloses that it uses headless Chrome, drops navigation/sidebars/cookie banners, and that results are compact. It also notes a surcharge for residential exits. However, it does not detail the exact behavior of async mode or token collection, though that is partially covered by the sync parameter schema. With decent annotation coverage, a 4 is justified.

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 concise and front-loaded with the main purpose and usage. The behavioral context (headless Chrome, content filtering) is early, and the cost/alternative comparison is efficient. It is not overly long, and each sentence adds value. A minor deduction for not mentioning the async token flow in the description, but it is covered by the sync parameter, so overall strong.

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 9 parameters, 2 required, and an output schema is absent, the description covers the essential use case and behavior. It explains key parameters like sync and max_age effectively through the schema and description combined. However, it does not explain the return format or token collection process fully, relying on the get_result sibling. Considering the complexity and that annotations carry some info, a 4 is appropriate, not a 5 because the async workflow could be clearer.

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 parameters thoroughly, including details like max_age format and idempotency_key behavior. The description does not need to re-explain parameters. It adds a note that 'removed ads and banners are gone from html, markdown and summaries too' for page_options, which is a useful extra beyond the schema. However, this is minor, so a 3 baseline is appropriate given high 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 clearly states the tool makes a POST to /markdown, renders the page in headless Chrome, and converts main content to clean Markdown with specific elements kept and others dropped. This is a specific verb+resource with detail that distinguishes it from fetch_html and scrape_url, both siblings with different purposes.

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 explicitly says 'Start here when you want to READ a page' and contrasts with fetch_html, noting that fetch_html returns the whole DOM which is larger and says nothing extra about meaning. It also highlights cost (1 credit) as a differentiator. This provides strong guidance on when to use and when not to use.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: it can indicate cache/reuse behavior, analysis failure reasons, and webhook delivery status. This helps the agent understand diagnostic value beyond the annotation flags. No contradictions.

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 paragraphs. The first front-loads the tool's coverage with a scannable list; the second adds usage context. Some minor redundancy ('webhook delivery' appears twice), but every sentence contributes to purpose or usage.

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 2-parameter read-only metadata tool with no output schema, the description covers what data is returned (stage durations, store origin, webhook status), its relationship to get_result, and the recommended use case. It is sufficient for an agent to select and invoke correctly.

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

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

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description does not add any extra semantics about token or project_id beyond what the schema already provides, so no upgrade.

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 that the tool returns metadata about a single past request, excluding the result itself. It lists specific content areas (what was asked, stage durations, store origin, webhook delivery) and explicitly contrasts with sibling get_result, making its purpose distinguishable from all 13 sibling tools.

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

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

The description gives a direct usage scenario: 'Reach for this one when a call did not do what you expected.' It explains what it can reveal (reused result, failure cause, webhook success) and names the alternative get_result for retrieving the result page. This is explicit when-to-use 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 mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: results are returned in the same form the original call would have produced, unfinished requests return {"status": "processing"}, results are kept for 30 days, and re-reading is free. 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 longer than a one-liner, but every sentence carries essential information: endpoint, return-shape mapping, async collection mechanics, retention/free re-reads, and retry behavior. It is front-loaded with the endpoint and purpose, with supporting details in logical order.

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 must explain return values, and it does: Markdown stays Markdown, structured operations are objects, screenshots are images, and scrapes become combined objects. It also covers the pending state and retention duration, so an agent has enough information to call and handle the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that the token is the async handle produced by earlier non-sync calls and that it converts that token into the final result. It also clarifies that re-reading an existing token is free, which informs how the token parameter should be treated.

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 opens with a precise verb and resource: 'Exposes GET /result/:token. Returns the result of a past request.' It immediately distinguishes this tool from sibling tools by explaining that it is the collection mechanism for async calls, turning a returned token into the corresponding result.

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 when-to-use context: 'any tool called without sync: true answers with a token, and this turns that token into the result.' It also covers the free re-read case. It does not explicitly contrast with siblings like get_request or list_requests, but the async-token trigger is a strong usage signal.

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 readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: remaining quota resets per period, prices differ greatly between operations, and quota_exceeded is a signal that this usage number was exhausted. This goes beyond annotation coverage and helps the agent anticipate outcomes.

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 definition is concise and front-loaded: the first sentence clearly defines the tool's output, and the second paragraph adds a concrete, valuable example without redundancy. Every sentence earns its place, and the 17x pricing example strengthens understanding of when to use the tool.

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

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

For a zero-parameter, read-only introspection tool, this is complete. It explains what data will be returned (plan limits, remaining usage, operation costs), when it is useful, and how to interpret a related error. No output schema is required to understand the tool's role.

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

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

The tool has zero parameters and 100% schema description coverage, so the baseline of 4 applies. The description correctly focuses on what the tool reports rather than parameters, since there is nothing to document.

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 exactly what the tool exposes: plan allowances, remaining usage for the period, and per-operation costs. The title reinforces the purpose as 'Check usage and prices', and the content is specific enough to distinguish it from any sibling 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?

The description gives explicit guidance on when to call it: before a run of expensive calls, and when interpreting a quota_exceeded refusal. This is actionable and tied to real decision-making, making the usage context unambiguous even without naming alternatives.

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=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it reveals a cost of 2 credits, that it is slower than other tools, and that it fetches the page itself rather than sharing a visit. This explains external side effects and performance characteristics that annotations don't cover. No contradictions 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 two short paragraphs with no fluff. It front-loads the core purpose in the first sentence, then adds cost and latency context, and ends with a specific usage note about scrape_url. Every sentence earns its place; it is efficient and well-structured.

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 tool with 10 parameters and no output schema, the description covers purpose, cost, latency, and an interaction with a sibling. It does not describe how to retrieve results (sync behavior, get_result) but those are covered in the schema and sibling tools. The description is adequate for an agent to understand the tool's high-level behavior and trade-offs.

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 has 100% description coverage, so all parameters (url, sync, device, labels, max_age, etc.) are already explained. The description does not add any parameter-specific meaning; it only adds context about cost and page-fetch behavior, which is not tied to any single parameter. Since the schema fully documents parameters, the 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 clearly states the action (runs a real Google Lighthouse audit) and the specific resource (live page) with a list of metrics produced (performance, accessibility, best-practices, SEO, Core Web Vitals). It distinguishes this tool from siblings by its unique audit capability and even references the HTTP endpoint (POST /lighthouse). It is not a tautology and immediately conveys what the tool does.

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 cost and latency guidance (2 credits, takes longer than anything else) and explicitly warns about combining with scrape_url (costs two page visits), which implies when to avoid it. However, it does not explicitly name alternative tools for when to use this one over others (e.g., 'use fetch_html for raw HTML'). The context is clear enough to infer appropriate usage, but lacks explicit exclusions or alternatives.

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, idempotentHint, and non-destructive behavior. The description adds token-scoped visibility, the 30-day request count metric, delivery-location details, and the billing distinction between projects and organization credits. This is valuable context beyond the annotations.

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

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

The description is two sentences, front-loaded with what the tool returns and then why it matters for tool selection. Every sentence earns its place with no fluff.

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

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

For a zero-parameter, read-only list tool, the description covers the key return fields and the practical workflow (call this first to obtain a project_id). It compensates for the lack of an output schema by naming the fields included, making it sufficient 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?

The tool takes no parameters and schema coverage is 100%, so there is no parameter semantics burden on the description. The baseline of 4 for zero-parameter tools 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 the tool lists all projects reachable by the token, including 30-day request counts and result delivery locations. It also frames itself as the entry point for every project_id-taking tool, clearly distinguishing it from siblings like list_requests and get_usage.

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 explicitly says 'Start here: every other tool takes a project_id from this list,' telling an agent when to call it. It also clarifies that choosing a project does not affect cost, which guides selection. It does not name alternative tools for when not to use it, but its role as a prerequisite 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 readOnly and idempotent behavior, so the bar is lower. The description adds valuable behavioral details beyond annotations: newest-first ordering, token exposure per request, scrape as a single entry with internal child operations, and that the scrape token returns all children. This is exactly the kind of nuance an agent needs.

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?

Every sentence earns its place: the first sentence states the core behavior, the second provides a concrete use case, the third clarifies scrape behavior, and the fourth explains label filtering. No filler or redundant restatement of the title.

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

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

For a read-only listing tool with a fully described schema and strong annotations, the description covers the key behavioral nuances that an agent could not infer from the schema alone. It explains the most important gotcha (scrape entries) and the intended workflow with get_result. Nothing essential 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 schema already documents all parameters. The description adds context about labels matching exactly, which repeats the schema's wording, and explains the scrape token semantics, but does not enrich the meaning of url, limit, offset, or operation beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it lists a project's recent requests, newest first, with each one's token. It also differentiates this from fetching results by pointing to get_result for obtaining the actual result. This is clear and not a tautology.

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 usage context: check this tool before fetching a page to potentially reuse an existing result, and use labels to filter requests. It names get_result as the follow-up tool. It does not explicitly list exclusions (when not to use), but the guidance is specific and actionable.

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

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

Beyond the annotations, the description discloses billing semantics ('billed and stored exactly as the individual call would be'), the partial-failure response shape, and the visit-sharing exceptions. The idempotent and non-destructive hints are not contradicted, and the extra context materially improves the agent's model of the call.

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

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

The description is front-loaded with the core purpose and each paragraph earns its place: behavior, response shape, and cost caveats. The length is justified by the number of interacting options, and there is no redundant wording.

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 tool with no output schema, it describes the response structure explicitly. It also covers the important edge cases around residential surcharging, lighthouse, screenshot options, and partial failures, making the tool safely callable without needing to infer behavior from the schema alone.

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 documents all 13 parameters, so the baseline is 3. The description adds cross-parameter meaning by clarifying how operations and certain screenshot_options affect page-visit sharing and cost, which is not evident from reading the schema alone.

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: 'Exposes POST /scrape' and 'Runs any subset of the other operations in one request.' This makes the batching behavior clear and differentiates it from the individual sibling tools such as fetch_html, capture_screenshot, and lighthouse_audit.

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 explicitly explains when to prefer this tool: with a residential exit, several results from one page visit pay the surcharge once, while noting this is not a discount. It also gives when-not guidance by calling out lighthouse and screenshot options that force separate page fetches and therefore do not share the visit.

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

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

Beyond the annotations, the description reveals that this is the most expensive operation at 17 credits, that it runs a language model over the page, and that the output strips boilerplate. This gives the agent important cost and behavior context that annotations do not convey.

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

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

The description is compact and front-loaded, with the core behavior in the first sentence and the cost/usage guidance in the second. Every sentence earns its place, and the alternative-tool guidance is integrated without verbosity.

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?

The description, combined with the complete parameter schema and annotations, gives the agent enough to select and invoke the tool correctly. It explains cost, output format, and when to prefer a sibling. It does not detail the async return behavior, but the schema's sync parameter and sibling get_result already cover that path.

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

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

All 9 parameters are already fully described in the schema, so the description does not need to repeat them. The high-level description correctly orients the agent toward the resource and result, but it adds no parameter-specific detail 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 names the exact endpoint ('POST /summarize'), states the output ('concise Markdown summary of the page's main content'), and specifies what is excluded ('navigation, ads and boilerplate'). It clearly separates this tool from cheaper page-fetching siblings like fetch_markdown by emphasizing that the summary itself is the product.

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 decision guidance: it is the most expensive option at 17 credits, and if the model is reading the page for itself, fetch_markdown is cheaper at 1 credit. It closes by stating the exact condition for using this tool: 'when the summary is the artefact being produced, not a step on the way to one.'

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