miromiro

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the extraction behavior: a URL that is itself an image returns a single 'source file' result, and results are capped at 100 by default with a 200 ceiling. It does not restate the widely documented caching and render/screenshot trade-offs that live in the schema, which is fine but leaves it short of fully rich 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?

Four sentences, each earning its place: trigger, scope of results, special case, exclusions, and the one parameter nuance worth surfacing. The trigger and the sibling routing are front-loaded where an agent will read them first.

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 an output schema present, the description need not explain return shape, and it correctly focuses on routing and scope. For a read-only extraction tool with a complete schema and annotations, nothing an agent needs to select or invoke it 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 description coverage is 100%, so the schema already documents every parameter in depth (fresh/cache, render, screenshot, full_output, response_format). The description only echoes the limit defaults ('up to 100 by default; pass limit (up to 200)'), which is a restatement rather than added meaning. 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?

States a specific verb and resource ('the images from a page'), enumerates the asset kinds covered (photos, illustrations, backgrounds, favicon, social image) and the tagging scheme, and explicitly names the siblings it is not for. An agent can distinguish it from extract_svgs and extract_fonts without opening a 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?

Opens with the triggering condition ('Use when the user wants the images from a page') and gives explicit exclusions with named alternatives ('Not for: icons and vector logos (use extract_svgs) or fonts (use extract_fonts)'). It also resolves the ambiguous case where the input URL is itself an image.

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 (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context beyond them: per-source tagging of results, the 40-item default cap, and the +5 credit surcharge for render=true. It stops short of describing failure modes or rate limits, which the schema's render note partially covers instead.

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

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

Front-loaded with the trigger, then the special cases and limits in four tight sentences with no filler. A minor redundancy with the schema on the limit/render details keeps it from a 5.

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?

An output schema exists so return values need no explanation. The description covers the edge case where the URL is itself an audio file, the JS-runtime case, the credit cost, and pagination limits, which is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates limit ('up to 200') and the render surcharge, both of which the schema already documents in more depth, so it adds little parameter meaning of its own.

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 ('the audio files on a page') and enumerates exactly what counts as audio: <audio>/<source>, og:audio, podcast enclosures, download links. This distinguishes it cleanly from sibling extractors like extract_videos, extract_svgs and extract_fonts.

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 trigger ('Use when the user wants the audio files on a page') and a follow-up condition ('If a JavaScript player mounts the audio at runtime, call again with render=true'). It does not, however, name the sibling tools to prefer for non-audio media, so the routing guidance is clear but not complete.

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/idempotent/openWorld, so the safety profile is covered. The description goes beyond them by disclosing the confidence score and the meaning of `signals.explanation` ('css-var'/'theme-color' vs 'usage'), which is genuine interpretive guidance. However, it omits caching behavior and the credit costs that the schema documents for fresh/render, leaving a gap that a 3 reflects.

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

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

Front-loaded with the trigger condition, then the return shape, then the presentation caveat, then the exclusions — a clean triage order. Despite its length, every clause carries distinct information (trigger, output, interpretation warning, sibling boundaries).

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 output schema covers return values, and the description still supplies the one thing an agent would otherwise get wrong: not to present inferred colors as the official palette. Combined with sibling routing for extract_code and extract_design_tokens, an agent has everything needed to call and report 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% and all five parameters are already documented in detail, including the render surcharge and cache semantics. The description adds nothing about url, fresh, render, screenshot or response_format, 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 and resource ('a site's brand: its colors, fonts, logo, theme or social links') and grounds it in concrete user phrasings like 'what colors does stripe use'. The 'Not for:' clause explicitly separates it from extract_code and extract_design_tokens, so an agent can route without opening either 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?

Gives both when-to-use ('Use when the user wants a site's brand') and when-not-to-use with named alternatives for markup/layout and the full token list. The alternative routing is explicit rather than inferred.

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

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

Goes far beyond the annotations by disclosing browser rendering behavior, caching, credit implications, auto-detection fallback, SVG hosting, Elementor/Shopify import constraints, and the `downloadUrl`/`previewUrl`/`pagePreviewUrl` outputs. The read-only, open-world, idempotent annotations are consistent with an extraction tool, and the description adds operational caveats the agent could not infer from annotations alone.

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 opening sentence is front-loaded and useful, but the description is extremely long and dense, mixing invocation guidance with extensive post-extraction editing, cleanup, and handoff instructions. Many sentences are valuable workflow rules, but they make the tool definition hard to scan and exceed what is needed for tool selection.

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 an 11-parameter extraction tool with an output schema, the description is more than complete: it covers framework-specific outputs, caching, rendering, fallback behavior, SVG handling, and follow-up page assembly. An agent has enough context to call it correctly and understand the main caveats.

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 already 100%, so the schema carries most parameter definitions. The description still adds meaningful selection guidance around `section` vs `selector`, framework choices, and when to use `fresh` or ask the user for a target format, but much of its parameter detail duplicates the schema text rather than adding wholly new semantics.

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?

Starts with a specific verb and resource ('extract section as code') and immediately scopes it to rebuilding, cloning, porting or restyling real website sections. It clearly distinguishes itself from the other extract_* siblings by focusing on generated component code rather than assets, tokens, fonts, or media.

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

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

Explicitly states when to use it, which frameworks map to which user requests, how to pick `section` vs `selector`, and what not to use it for ('whole-page scraping, page text, or sites that need a login'). It also tells the agent to ask for the desired format rather than converting between formats.

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

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

Goes well beyond the read-only/idempotent annotations: it discloses that only values and counts are returned (not layout or element mapping), that light+dark themes return the union of both, and that lists trim to 60 per group unless limit is raised. It also warns against picking colors by frequency.

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?

Dense and front-loaded with routing and scope first, then format options, then exclusions and limit behavior. It is a long, multi-clause single paragraph with some run-on sequencing, but nearly every clause carries decision-relevant 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?

Given an output schema exists, return-value specifics need not be restated, and the description still covers scope, format choice, theme handling, trimming limits, and sibling routing. Nothing an agent needs to select and call this tool correctly is absent.

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 carries full semantics for all 8 parameters including format, limit, render, and screenshot. The description echoes format semantics (paste-ready :root block, tailwind.config, W3C file) and the limit cap without adding new parameter-level detail. 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+resource (extract a site's complete token system) and enumerates the concrete scope covered (colors, fonts, spacing, radius, shadows, gradients, breakpoints) plus the three output formats. It explicitly differentiates from siblings extract_code and extract_brand by name.

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 (complete token system, or paste-ready code block), when-not-to ('Not for: a short brand summary'), and a routing rule with the alternative named ('if the user asked to rebuild or clone a section, use extract_code'). Format-selection guidance for json/css/tailwind/dtcg is folded in.

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 annotations already declare this is a read-only, idempotent, open-world operation, so the safety bar is low. The description contributes genuinely non-obvious domain behavior: on type-foundry sites the served families are demo cuts with stripped features, flagged demo:true, and the agent is told to pass that caveat on. Default trimming behavior is also disclosed, though caching/auto-render behavior is only in the schema.

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

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

Front-loaded with the use case, then payload, then the demo caveat, then exclusions — the ordering matches how an agent needs the information. It is dense with semicolons and clauses, but every clause carries a distinct instruction rather than padding.

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 an output schema present, return shape need not be spelled out, and 8 parameters are fully covered by schema descriptions plus targeted guidance in the description. Accuracy-critical edge cases (demo fonts, list trimming, wrong-tool boundaries) are all addressed, so an agent has everything needed to call and interpret this 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 baseline is 3; the description earns above that by telling the agent why and when to use fields='families' and limit rather than merely restating their types. The caveat that the 50-entry trim is a default rather than a hard cap is the kind of semantic detail the schema alone would bury.

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 and enumerates exactly what is returned: every @font-face file with family/weight/style/format, Google Fonts links and preloads, grouped per family. It also explicitly disambiguates from siblings ('Not for: colors (use extract_brand) or code (use extract_code)'), so an agent can pick it without opening a 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?

Opens with the triggering user intent ('Use when the user asks which fonts a site uses or wants to match its typography') and names the two alternatives to use instead for adjacent asks. It goes further with narrower routing: pass fields='families' for just the grouped output, and pass limit up to 200 when the 50-entry trim cuts results.

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 (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description still adds behavior annotations don't carry: the +5 credit surcharge for render and the runtime-injection caveat that explains why a static pass may return nothing. It omits any note on caching or output shape, but the credit/cost context is genuinely useful.

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, front-loaded with the usage trigger, then the render fallback, then the limit caveat. No filler, and the most decision-relevant guidance (when to call, when to escalate to render) comes first.

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 100% schema coverage, an output schema present, and rich annotations, the description needs only the intent trigger and the render-escalation rule, both of which it supplies. It leaves pagination/return-shape explanation to the output schema, which is fine; nothing an agent needs to call 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 description coverage is 100% and the render/limit schemas are extremely thorough, so the schema does the heavy lifting. The description only restates the default 20 / up to 200 limit and the render cost, adding no syntax or semantics beyond what the schema already documents. 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 frames the tool by intent ("Use when the user wants a site's Lottie or animation JSON files"), which pins the resource as specifically Lottie/animation JSON. That resource is distinct from siblings like extract_svgs, extract_videos and extract_audio, so an agent can tell it apart even though no sibling is named explicitly.

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 triggering condition (user wants Lottie/animation JSON) and a follow-up rule for the common failure mode ("pass render=true when the static call finds none"). It stops short of naming alternative extraction tools or stating when-not-to-use, keeping it at a strong-but-not-exhaustive level.

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 annotations, it discloses billing behavior (flat credits per page, free within 24 hours), paid-plan restrictions, the free-plan error response, retry semantics when `complete` is false, cache behavior, and guidance not to regenerate section code. This is exactly the kind of operationally important context annotations cannot express.

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 and every sentence carries useful operational guidance, but it is a dense single paragraph mixing purpose, billing, retries, and workflow instructions. It could be structured more cleanly, though little is truly wasted.

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 complex paid extraction workflow, retry behavior, and sibling alternatives, the description covers what an agent needs before calling. An output schema exists, so it does not need to fully explain return values, and its mention of `pagePreviewUrl` and `complete` 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%, so the schema already documents `url`, `theme`, and `framework`, including enums and defaults. The description reinforces that the URL should come from `list_site_pages` and that the framework applies to every section, but it does not add substantial parameter syntax or format 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 states a specific verb and resource: extract one complete page as code, returning every section top to bottom in the requested framework plus `pagePreviewUrl`. It explicitly distinguishes itself from `extract_code` by contrast with single sections, so an agent can route correctly among siblings.

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

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

It gives explicit when-to-use guidance: after `list_site_pages`, or when the user wants a complete page rather than a single section. It also states when-not/alternative guidance by directing users to `extract_code` for single sections and explains paid-plan-only behavior and the free-plan error path.

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 a safe, idempotent, open-world read (readOnlyHint/idempotentHint true, destructiveHint false), so the safety burden is lifted. The description adds genuinely useful behavior beyond that: long markup is trimmed by default, only 20 results come back unless asked, and full_output restores complete code. It does not cover caching or rate-limit behavior, and the limit/full_output defaults are partly restated from the schema.

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

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

Three tight, front-loaded sentences: trigger first, exclusion second, output/defaults third. Slightly redundant with the schema on limit and full_output, which costs a bit of efficiency, but 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?

An output schema exists, so return values need no explanation; the description still tells the agent the response shape (inline markup + .svg URLs) and the trimming default. Combined with annotations covering safety, this is complete for a 7-parameter extraction tool.

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

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

Schema description coverage is 100%, so every parameter is already documented with rich guidance (fresh, render, screenshot, response_format all have detailed schema text). The description only restates the limit and full_output defaults, adding no syntax or format detail the schema lacks. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (extract SVGs) and immediately narrows the scope to a site's icons or vector logos, plus names the output form (inline markup plus external .svg URLs). It explicitly distinguishes itself from extract_assets, so an agent can route correctly without opening either 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?

Gives a positive trigger ('when the user wants a site's icons or vector logos') and an explicit exclusion with the alternative named ('Not for: raster images (use extract_assets)'). Nothing about tool selection 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 declare readOnly/idempotent/non-destructive, but the description adds behavior they cannot carry: the 24h cache, the +5 credit render surcharge, that platform URLs are answered without a fetch, that the file itself cannot be downloaded through MiroMiro, and the default 40 / max 200 return budget. This is unusually rich disclosure of cost and side-effect semantics.

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

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

Front-loaded with the trigger and the primary source taxonomy, and nearly every sentence carries a distinct behavior (credits, caching, platform handling, pagination). It is dense with parentheticals and mid-sentence code spans, which slightly hurts scanability, but there is little genuinely dead text.

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 an output schema present the description need not document return values, and annotations cover the safety profile, so the remaining burden is behavioral and cost guidance — all of which is supplied (cache, credits, automatic browser fallback, render re-call, pagination). Nothing an agent needs to call this 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 description coverage is 100%, so the baseline is 3; the description lifts above it by giving video-specific render semantics the schema only states generically ('never pass render for these' platform URLs) and restating the limit ceiling. It does not add much for url, fresh, screenshot or full_output, so it is not a 5.

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

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

States a specific verb+resource and enumerates exactly what qualifies as a video on a page: <video>/<source>, og:video, YouTube/Vimeo/Wistia/Loom embeds, direct links, and JSON-LD VideoObject. This scope detail cleanly separates it from siblings like extract_audio, extract_lottie and extract_assets without the agent needing to open any 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?

Opens with an explicit trigger ('Use when the user wants the videos on a page') and then gives hard when-not rules: never pass render for platform URLs, do not retry on a 403 that says the browser was refused, and call again with render=true only when the hint names a JS player. Alternative paths (platform-URL path vs fetch path vs structured-data path) are each tied to their condition.

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 that the tool is free on every plan (0 credits), where pages come from (sitemap, else homepage links), the exact result shape (`pages`, `templates`, `suggested`), template grouping behavior, and premium-gating behavior with `premium.reason` and `premium.upgradeUrl`. This is unusually rich behavioral context for a read-only tool.

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 trigger condition and is dense with useful workflow details. It is somewhat long as a single paragraph and could be easier to scan with bullets, but nearly every sentence earns its place and no significant repetition appears.

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 an output schema and full annotation coverage, the description is complete: it covers trigger, source of data, result structure, cost, required user confirmation, next-step extraction, and premium failure handling. Nothing an agent needs in order to call 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 description coverage is 100%, so the schema already documents both `url` and `response_format`. The description does not add syntax or format details beyond the schema; its cost discussion (`creditsPerPage`) applies to the follow-up extract_page call rather than this tool's parameters. 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: listing a website's pages, either to get the site as code or to answer which pages exist. It clearly distinguishes the tool from extraction siblings by saying to call extract_page only after the user chooses pages.

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 trigger conditions ('Use when the user wants a whole website... or asks which pages a site has'), a required workflow (show the list, state counts and costs, ask before extracting), an explicit prohibition ('Never extract every page of a big site unprompted'), and a fallback path when `premium` appears. Alternatives and exclusions are both covered.

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