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

Annotations already cover readOnly/idempotent/destructive/openWorld, yet the description still adds non-obvious operational traits: 32 KB payload cap, 60 RPM throttle, L402 payment option (15 sats), demo bypass, and an HTTP 400 failure on invalid input. These are exactly the constraints an agent must know before calling.

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?

Purpose is front-loaded in the first sentence and every subsequent clause carries information, but the final sentence is telegraphic ('Stateless read-only edge call (max 32 KB, 60 RPM)', 'L402 (15 sats)') and packs several unrelated facts into one dense run-on.

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 covers return values and annotations cover safety, and the description fills the remaining gaps: supported standards, size and rate limits, payment/demo access, and error behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by disclosing that 'feed_standard' defaults to 'rss_2_0', a default not stated in the schema. The remaining parameter mentions (items_json contents) merely restate 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?

Names a specific verb (transforms) and both input and output resources (JSON item collections / article card arrays → RSS 2.0, Atom 1.0, JSON Feed 1.1). It also names the sibling it is not (crawl_sitemap_urls) 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?

'Use when syndicating blog articles, product announcements, or changelog cards to RSS readers and AI agents' gives concrete positive triggers, and the sitemap clause explicitly excludes the nearest alternative. Both when-to-use and when-not-to-use are present.

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 readOnly/idempotent/non-destructive annotations, it discloses payload cap (32 KB), rate limit (60 RPM), statelessness, demo-mode and L402 payment requirement (15 sats), and the 400 error on invalid input — none of which the annotations carry.

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

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

Two sentences, front-loaded with purpose before routing guidance, and the operational facts are packed into a compact clause. Dense but essentially waste-free; only the parenthetical enumeration of limits feels slightly crammed.

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 a 100%-covered schema, an output schema handling return values, and annotations covering the safety profile, the description still supplies limits, auth options, and failure mode. Nothing needed 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 coverage is 100%, so the baseline is 3; the description adds a real detail the schema lacks — that filter_criteria defaults to 'all_entries' — and names sitemap_xml as the accepted input. It does not, however, explain max_results semantics beyond the schema's own text.

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 ('Parses XML sitemaps and sitemap index files into structured URL trees') plus the filter dimension, and explicitly distinguishes itself from extract_page_hyperlinks. An agent can route between the two 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 concrete when-to-use scenarios (discovering domain architectures, mapping crawl frontiers, indexing blog/product catalogues) and names the alternative for the adjacent case, plus the condition that selects it ('raw HTML').

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 only declare readOnly/idempotent/non-destructive/openWorld=false; the description goes well beyond them by disclosing statelessness, the 32 KB payload cap, the 60 RPM rate limit, the demo mode and L402 pricing (15 sats), and the HTTP 400 failure mode for invalid input. Those are operational constraints an agent cannot infer from any structured field.

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?

Purpose and the sibling alternative are front-loaded, then operational facts are packed into a single dense sentence. Nothing is redundant, but the rate-limit/payment/error clause is compressed into a run-on that costs some scanability.

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 shape need not be explained, and the description still covers the inputs, the default profile, the size and rate ceilings, the payment path, and the failure status. For a read-only three-parameter auditor, an agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds a default the schema omits ('detection_profile' defaults to 'heuristic_dom_overlay') and reiterates the html_content input and demo flag. It does not explain target_domain's publisher-pattern lookup, leaving one property to 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?

States a specific verb and resource — audit DOM hierarchies for soft paywalls, blur overlays, modal gates, plus concealed body text recovery. The title's phrasing is echoed but the description adds concrete detection targets (blur overlays, modal gates) rather than restating the name, and it distinguishes the tool from evaluate_seo_diagnostics by naming that sibling 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?

Gives both when-to-use (diagnosing paywall obstructions, subscriber gating scripts, content access barriers) and when-not-to-use with the exact alternative: 'for assessing general SEO hygiene, use evaluate_seo_diagnostics instead.' That is an explicit routing rule an agent can act on without reading either schema.

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 substantial non-obvious behavior: statelessness, a 32 KB payload cap, 60 RPM throughput, a demo bypass, an L402 payment of 10 sats, and HTTP 400 on invalid input. The only shortfall is that it doesn't say what happens at the rate limit (429 vs queue) or whether the sats charge applies per 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?

Front-loaded with purpose, then usage, then operational constraints in a tight single paragraph. The third sentence packs several unrelated facts (size cap, rate limit, demo, L402, error code) into one clause chain, which is dense but every element is relevant to calling the tool correctly.

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 needn't explain return values, and it covers the remaining gaps an agent needs: auth/payment path, size and rate limits, failure mode, and the default audit scope. Complete for a single-required-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by disclosing 'audit_level' defaults to 'comprehensive_audit' and implicitly scoping 'html_content' to a raw HTML string. It never mentions 'target_keyword', leaving that parameter entirely to 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?

States a specific verb ('Audits') plus the exact resources checked (heading structures, title lengths, meta descriptions, alt tags, OpenGraph) and the output artifact (health score). It also names the sibling it is not (scrape_readable_article), so an agent can discriminate 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?

Explicitly enumerates three triggering scenarios (auditing landing pages, pre-publish SEO compliance, crawl friendliness) and names the alternative tool with the condition that selects it ('for extracting article bodies, use scrape_readable_article instead'). Nothing is left to inference.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds material context the annotations cannot: statelessness, a 32 KB input ceiling, 60 RPM throttling, access via '?demo=true' or L402 payment of 10 sats, and an HTTP 400 failure mode for invalid input. Those are exactly the operational constraints an agent needs before calling a rate-limited, paywalled edge endpoint.

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 purpose then routing, with zero filler. The final sentence is a dense run-on of parentheticals (size cap, rate limit, payment, defaults, error code) that would scan better as a short list, which 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-shape explanation is unnecessary, and the annotations cover the safety profile. The description fills the remaining gaps an agent would care about: input limits, throttling, auth/payment paths, and failure behavior.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes slightly beyond by disclosing the default value of 'conversion_mode' ('clean_semantic_article'), which the schema does not declare. It does not otherwise explain the tradeoffs among the three enum modes, so it stops short of 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 and resource ('Converts raw HTML pages into clean, boilerplate-free, LLM-optimized Markdown') and names the exact output characteristics ('preserved hyperlinks and headings'). It also explicitly distinguishes itself from the sibling parse_html_tables, 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 an explicit use condition ('Use when ingesting raw web documents or blog posts into agent context windows') and an explicit alternative with its own condition ('for isolating tabular data into structured datasets, use parse_html_tables instead'). The when-to-use and the sibling exclusion are both present.

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, closed-world), and the description adds non-obvious operational facts: statelessness, a 32 KB payload cap, 60 RPM throttling, demo mode or L402 payment at 10 sats, and HTTP 400 on invalid input. These are runtime constraints an agent could not infer from the schema or annotations, which is exactly what this dimension rewards.

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?

Purpose is front-loaded in the first sentence, followed by usage then runtime constraints, with no filler. The final sentence packs size, rate, auth, default, and error details into one dense parenthetical, which is efficient but slightly hard to parse in a single read.

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, and the description covers the remaining gaps an agent needs: statelessness, input size, throughput, payment/auth path, and failure code. Nothing material for a correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the non-defaulted value that extraction_focus defaults to 'all_contacts' – information the schema itself does not state. country_hint is left entirely to the schema, keeping it below 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 concrete verb plus four specific resource types (emails, phones, physical addresses, social handles) and the source scope (web text and DOM footers). It explicitly contrasts with parse_html_tables, so the agent can separate it from the closest sibling without reading 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 three positive use cases (sales lead research, business contact directories, customer service info) and an explicit exclusion routing structured tabular input to parse_html_tables. The when/when-not pair is fully resolved.

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, and the description goes well beyond them: stateless edge call, 32 KB payload ceiling, 60 RPM rate limit, '?demo=true' trial or L402 payment of 10 sats, and HTTP 400 on invalid input. These are operational facts an agent cannot get from anywhere else and that materially affect call planning.

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 dense sentences, front-loaded with purpose, then routing, then operational constraints. Nothing is wasted, though the pricing/payment clause is packed into the same sentence as the rate limit, making the tradeoff-heavy tail slightly harder to scan.

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 stateless, read-only extractor with a full output schema, annotations covering safety, and 100% schema coverage, the description closes every remaining gap: cost model, rate limit, size ceiling, failure mode, and sibling routing. An agent has everything needed to decide and call 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, but the description adds a value not present in the schema: link_scope defaults to 'all_links'. It also reinforces that html_content is the required input. It does not explain base_url resolution semantics beyond what the schema already says, so it stops short of 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?

Specific verb triple (extracts, normalizes, filters) plus concrete resource types (hyperlinks, anchor texts, downloadable asset targets) read from HTML. It is immediately distinguishable from siblings like scrape_readable_article and sanitize_html_content because the description names the exact artifact produced.

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 lists three concrete use cases (site crawlers, broken-link audits, citation extraction) and then explicitly routes the agent away to scrape_readable_article when the goal is article narrative text. That is an explicit when-to-use plus a named alternative, which is the top of the scale.

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 read-only/idempotent/non-destructive, but the description adds genuinely new operational context: stateless edge call, 32 KB payload cap, 60 RPM rate limit, and auth via '?demo=true' or L402 (10 sats). HTTP 400 error behavior is also disclosed. It stops short of describing the return payload shape, but with an output schema present that is acceptable.

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 front-loaded sentences, no filler, with purpose first and the routing alternative immediately after. The final sentence is dense with limits, defaults, and pricing, but every clause carries information an agent needs.

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 extraction tool with an output schema, the description supplies everything else that matters: size limit, rate limit, auth/payment path, invalid-input behavior, and parameter default. No operational gap remains for an agent 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 coverage is 100%, so the baseline is 3, but the description adds value the schema does not: it states that 'metadata_targets' defaults to 'all_protocols', which is not encoded as a default in the schema. It does not explain include_favicons, but that parameter is fully documented 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?

States a specific verb and enumerates the exact resources extracted (OpenGraph, Twitter Cards, canonical URLs, JSON-LD), and explicitly names the sibling extract_page_hyperlinks as the different tool. An agent can distinguish this from extract_structured_json_entities or extract_page_hyperlinks 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?

Provides explicit when-to-use triggers (social share cards, author identity, breadcrumbs, rich snippets) plus an explicit when-not with the alternative tool named ('for scanning page hyperlinks ... use extract_page_hyperlinks instead'). Routing is unambiguous.

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, and the description adds genuinely new operational context: statelessness, the 32 KB input ceiling, 60 RPM rate limit, the ?demo=true bypass or L402 pricing at 10 sats, and the HTTP 400 failure mode. That is exactly the kind of behavioral detail structured fields do not carry.

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 that front-load the purpose then pack constraints into a compact clause list. The second sentence is dense and semi-colon heavy, but nearly every fragment (limits, auth, error) 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?

With an output schema present, return values need no explanation; the description still covers input limits, rate limits, payment/auth paths, and error behavior, which is everything an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds the non-obvious fact that extraction_mode defaults to inner_text, which the schema does not state. Required inputs are also named, giving more than 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?

Opens with a specific verb+resource ('Evaluates CSS selector queries against HTML DOM trees') and enumerates the three output representations. It distinguishes itself from the closest sibling by naming extract_contact_info as the tool for unstructured contact parsing.

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 concrete positive triggers ('pricing badges, product titles, review cards, navigation breadcrumbs') and one explicit exclusion routing to extract_contact_info. It does not mention adjacent siblings like parse_html_tables or extract_page_hyperlinks, but the core when-to-use guidance 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 cover readOnly/idempotent/non-destructive/closed-world, and the description layers genuinely new operational context on top: stateless edge call, 32 KB payload cap, 60 RPM rate limit, L402 payment of 10 sats, ?demo=true, and HTTP 400 on invalid input. It stops short of describing how tables that fail min_rows are reported, but the constraint disclosure is well above the annotation baseline.

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 dense sentences, front-loaded with the core action before use cases and operational limits. The second sentence stacks several facts (size, rate, formats, payment, error code) and reads a bit like a spec dump, but nothing is 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 stateless parser with a full schema and an output schema, everything an agent needs is present: input format expectations, output representations, size and rate ceilings, auth options, and failure behavior. Return-value details are correctly delegated to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by documenting the output_format default ('markdown_and_json'), which the schema does not state, and by naming html_content explicitly. min_rows is left to the schema, which is acceptable given full 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?

States a specific verb and resource ('detects and parses HTML table elements') plus the two output representations (JSON record arrays and GFM markdown grids). It names a sibling it is not, extract_clean_markdown, 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 concrete positive cases (financial statements, product comparison grids, sports statistics) and an explicit negative case with the alternative tool named ('for extracting raw clean markdown prose, use extract_clean_markdown instead'). The when/when-not pair is fully specified.

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 carry readOnly/idempotent/non-destructive, but the description adds operational facts annotations cannot: 32 KB payload cap, 60 RPM rate limit, stateless edge execution, default strictness, demo/L402 payment at 10 sats, and HTTP 400 on invalid input. Size limits, rate limits, and payment requirements are exactly the pre-call knowledge 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?

Three sentences with the purpose front-loaded ahead of routing and operational detail — correct ordering. The final sentence is dense, packing size, rate, defaults, demo mode, L402 pricing, and error behavior into one clause-heavy run, which slightly hurts scanability.

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-value documentation is not required, and annotations cover the safety profile. Remaining agent-critical gaps — payload cap, rate limit, default policy, cost, and failure mode — are all addressed, so nothing needed 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 baseline is 3; the description goes slightly beyond by declaring the default value for 'sanitization_strictness' ('strip_scripts_and_iframes'), which the schema does not state. It does not add semantics for 'preserve_images', leaving that entirely to 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?

Opens with a specific verb+resource ('Sanitizes raw HTML') and enumerates exactly what is removed (script tags, iframes, inline event handlers, data URIs), so the agent knows the transformation precisely. It also names the sibling it is not (extract_clean_markdown), separating the two without requiring schema inspection.

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?

States the triggering condition explicitly ('preparing untrusted third-party web content for rendering in agent dashboards or email clients') and names the alternative with the condition that selects it ('for converting clean HTML into markdown, use extract_clean_markdown instead'). Both the when and the when-not are present.

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 genuinely new operational context: statelessness, a 32 KB payload cap, 60 RPM rate limit, demo-mode or L402 payment at 10 sats, and HTTP 400 on invalid input. Those are exactly the facts an agent needs before calling an edge endpoint.

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?

Purpose and the sibling alternative are front-loaded, and every clause carries information. The final sentence is densely parenthetical (limits, auth, defaults, error code all crammed together), which slightly hurts scannability.

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 values need no explanation; the description instead covers the constraints that matter — size cap, rate limit, auth/payment paths, failure mode, and the sibling escape hatch. Nothing needed for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by disclosing the default value of 'readability_profile' ('article_body_strict'), which the schema does not state. It does not explain include_byline's default, so it stops short of 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?

The opening sentence gives a specific verb (extracts) and names the exact resources returned: article body, bylines, timestamps, reading duration. It also distinguishes itself from the sibling extract_clean_markdown, 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?

It states the use case ('stripping navigation bars, advertisement containers, and cookie banners to isolate core editorial content') and names the explicit alternative with its selection condition ('for converting full HTML to markdown, use extract_clean_markdown instead'). Both when-to-use and when-not-to-use are present.

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