Plainport

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

Goes well past the annotations (which already establish read-only and idempotent) by disclosing determinism, three hard limits (200k combined characters, 2,000 result parts, 8 ms budget), and a remediation step for large divergent inputs. This is exactly the kind of constraint an agent cannot infer from structured fields; only the failure mode (what is returned when a limit is hit) is left implicit.

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, each earning its place: purpose first, then usage, then constraints. No repetition of the title, no filler.

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

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

With an output schema present and rich annotations, the description only needs to add constraints and semantics, and it largely does. The one hole is 'ignore_whitespace', which is undocumented everywhere and would change diff results materially.

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 0%, so the description must carry parameter meaning. It covers granularity ('line- or word-level') and reflects the 200k character cap tied to before/after, but never mentions 'ignore_whitespace', leaving one of four required parameters entirely unexplained.

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 ('computes a deterministic line- or word-level diff') and describes the return shape ('typed add/remove/equal parts'). No sibling tool does anything similar, so the purpose is unambiguous even without explicit differentiation.

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 this when an agent needs structured change data' implies the usage context but names no alternative and no exclusion. There are no sibling diff tools to route away from, so the gap is mild, but selection guidance is still only implied rather than stated.

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 (readOnly, idempotent, openWorld, non-destructive), the description discloses concrete operational limits — 8 s timeout, 5 redirects, 768 KiB body, 500 links — and that only 'one public HTML page' is fetched, which is exactly the behavioral context annotations cannot convey. It also states link normalization/deduplication and same-origin classification.

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, both dense: the return contract first, then usage scope and limits. No filler, and the most decision-relevant facts (what it returns, when to use it, hard limits) are front-loaded.

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 structure, yet it summarizes the payload anyway; the one-public-page scope and all hard limits are covered. The only gap is that the semantics of `include_external` and the default for `max_links` are left to the schema, which does not document them.

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 33%: only `url` is documented in the schema, while `max_links` and `include_external` have no descriptions. The description partially compensates by mentioning the 500-link cap and same-origin classification (implying external links are included and tagged), but it never explains what `include_external` toggles or that `max_links` defaults to 100.

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 precise verb and resource ('Fetches one public HTML page') and enumerates the return payload (unique normalized HTTP/HTTPS links, anchor text, rel values, same-origin classification), which clearly separates it from metadata/markdown/feed siblings. It never names a sibling explicitly, so differentiation is inferred rather than stated.

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 this for bounded navigation discovery; it does not crawl the returned links' gives a clear positive context plus an explicit exclusion, preventing an agent from expecting recursive crawling. No alternative tool is named for the case where crawling or full-page text is wanted, which keeps it below a 5.

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

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

Beyond annotations, the description discloses concrete operational limits: 8 seconds, 5 redirects, 768 KiB, and 50 JSON-LD blocks. It also clarifies that it fetches exactly one public HTML page, which sets useful scope expectations for an open-world read operation.

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 compact sentences, front-loaded with the action and extracted fields, followed by clear usage context and hard limits. Every sentence contributes useful information without repetition.

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

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

For a single-parameter read-only tool with an output schema, the description provides everything needed: purpose, extracted metadata types, usage guidance, and operational limits. The output schema handles return-value documentation, so no important agent-facing context 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents the URL constraints. The description adds little parameter-level detail beyond reinforcing that the page is public and HTML, making the baseline score 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 uses a specific verb and resource: it fetches one public HTML page and extracts metadata. It enumerates the exact fields returned (title, description, canonical URL, robots, Open Graph, Twitter Card, feeds, JSON-LD), which lets an agent distinguish this from body-text conversion 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?

It explicitly says to use this when an agent needs page identity or structured data rather than body text, giving clear selection context. It does not name specific sibling alternatives like fetch_markdown or extract_links, so it falls short of fully explicit when-to-use/when-not guidance.

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

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

Annotations already declare read-only, idempotent, open-world and non-destructive, and the description goes well beyond them by disclosing hard operating limits: 8 s timeout, 5 redirects, 768 KiB remote body, 150k output characters. It also states the no-JavaScript constraint and that native text/markdown is preserved rather than re-converted — exactly the behavioral context annotations cannot 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?

Four short sentences, front-loaded with purpose then usage then caveat then limits — no redundancy with the title, and every clause (JS, native markdown, limits) earns its place by answering a foreseeable agent question.

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 two-parameter fetcher with an output schema and full safety annotations, the description covers the remaining risk surface: client-side rendering, redirect/timeout ceilings, body size, and output truncation. Nothing an agent needs to call it safely and interpret results 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 50%: url is documented in-schema while max_chars relies on min/max/default only. The description compensates by tying the 150k output-character ceiling to the tool's truncation behavior, giving the agent a reason to set max_chars rather than accept the 100k default. It still doesn't explain what happens at truncation (silent cut vs. marker), 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 specific verb and resource ('Fetches one public HTTP/HTTPS page') plus the exact output ('primary readable content as Markdown'). The phrase 'one public HTTP/HTTPS page' implicitly separates it from html_to_markdown (which converts supplied markup) and from multi-page crawlers, so an agent can place it correctly among its 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?

'Use this for article or documentation body text without page chrome' gives a clear positive condition, and 'It does not run JavaScript; use a browser tool for client-rendered pages' gives an explicit exclusion with a redirect target. It stops short of naming the sibling converters (html_to_markdown, extract_links) that an agent might otherwise confuse it with, so routing is inferred rather than stated.

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 and closed-world, but the description adds genuinely new limits (200k input, 150k output characters) and clarifies no network fetch occurs. Return format is carried by the output schema, so this is close to complete.

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 short sentences, each doing distinct work: what it does, when to use, param caveat, limits. Front-loaded with the core action and the key disambiguation.

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 agent can decide and call correctly: mutation profile from annotations, return shape from output schema, limits and routing from the description. Only the truncation semantics of max_chars remain unstated.

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 0%, so the description must compensate: it explains base_url's role (resolving relative links) and states input/output character limits matching html.maxLength and max_chars.maximum. max_chars itself is not described as a truncation control, leaving a small gap.

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+resource ('Converts supplied HTML into readable Markdown') plus an explicit negative scope ('without fetching a URL') that cleanly separates it from fetch_markdown, which is named directly.

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 exactly when to use it ('when the agent already has HTML'), names the alternative (fetch_markdown when Plainport should retrieve the page), and scopes base_url's narrower purpose.

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?

With readOnly/idempotent/openWorld annotations already covering the safety profile, the description adds real operational context: hard limits of 8 s, 5 redirects, 768 KiB, and 50 sitemap declarations, plus the caveat that the answer is guidance rather than authorization. It stops short of stating behavior for the common edge cases — robots.txt missing (404), unreachable, or non-200 — which materially affects how an agent should interpret the result.

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 the core action and evaluation rule, then usage guidance, then limits. No filler; 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?

An output schema exists, so return values needn't be spelled out, yet the description still names them (crawl delay, sitemaps) and enumerates fetch limits. The remaining gap is failure/absence semantics for robots.txt and how the result should be represented when no policy is found — relevant for a three-required-parameter tool with mostly undocumented parameters.

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

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

Schema coverage is only 33% (only 'url' is documented), so the description has to compensate and largely does: 'one path for a named user agent using longest-match allow/disallow precedence' explains what path and user_agent actually mean for the evaluation. It does not clarify wildcard handling for user_agent ('*' default) or that path defaults to root, leaving a small gap against the low 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 ('fetches an origin's robots.txt') plus the exact evaluation semantics (longest-match allow/disallow precedence for one path and user agent), and adds secondary outputs (crawl delay, sitemaps). This clearly separates it from siblings like inspect_url and parse_sitemap, which fetch or parse but do not evaluate robots policy.

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 this before automated retrieval' gives a clear triggering condition, and 'the result is policy guidance, not authorization' sets expectations about how to act on the output. It does not name alternatives (e.g., inspect_url for general header/status inspection), so the when-to-use side is strong while the when-not/alternative side is absent.

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

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

Annotations already declare read-only, non-destructive, idempotent, open-world, so the safety profile is covered; the description adds genuinely new operational context: 8 s timeout, 5 redirect cap, 768 KiB body cap that applies only to GET, and a filtered header allowlist. It does not say how failures, blocked hosts, or non-2xx statuses surface, which keeps it below a 5.

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

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

Four front-loaded sentences with no filler; the behavioral limits are condensed into a compact trailing clause. The telegraphic 'Limit: 8 s, 5 redirects, 768 KiB only for GET' is efficient but slightly clipped.

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 detail is not needed, and the limits plus method guidance cover the call mechanics. What is missing is error/failure behavior and whether redirect targets are re-validated against the public-URL rule, which matters for an open-world fetcher.

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?

With 50% schema coverage, the description carries real weight: it explains the semantics of the undocumented 'method' enum (HEAD = cheap check, GET = fallback for HEAD-hostile servers) and ties the 768 KiB limit to GET only. The 'url' parameter's constraint (no embedded credentials, public) is left 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+resource ('Resolves a public URL through bounded redirects') and what is returned ('status plus a safe allowlist of HTTP headers'). It also names the sibling it is not ('Use extract_metadata for HTML semantic metadata'), so an agent can route without opening another 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 explicit method selection rules — HEAD for cheap reachability/type checks, GET when a server mishandles HEAD — and names an alternative sibling for a different job. 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely operational detail not present in structured fields: an 8 s timeout, 5-redirect cap, 768 KiB payload ceiling, and 100-item ceiling. The 'does not fetch linked articles' line also scopes behavior in a way the 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?

Three tight sentences: capability and formats first, usage and exclusion second, hard limits last. No sentence is redundant and the most decision-relevant information is front-loaded.

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 structure need not be explained; the description covers formats, operational limits, and the key non-behavior (no article fetching). It does not mention failure behavior for malformed or unreachable feeds, which is the one gap for a network-fetching 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 50%: url is documented, max_items is not. The description's '100 items' limit indirectly explains max_items' upper bound and purpose, but it does not state the default of 50 or how items beyond the cap are handled. Marginal compensation for the coverage gap, so baseline 3.

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 ('Fetches and normalizes') plus the exact format scope (RSS 2.0, Atom 1.0, JSON Feed) and the output shape ('stable item list'). That format scope cleanly separates it from siblings like parse_sitemap, extract_links, and fetch_markdown 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?

Gives an explicit when-to-use condition ('consuming update feeds without format-specific parsing') and one clear exclusion ('does not fetch linked articles'), which steers the agent toward fetch_markdown/extract_links for article bodies. It stops short of naming a sibling alternative explicitly, so it is clear context rather than full routing guidance.

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

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

Beyond annotations that already declare this as a read-only, open-world, idempotent operation, the description adds concrete operational limits: 8-second timeout, 5 redirects, 768 KiB size cap, and 1,000-entry maximum. It also discloses that only uncompressed XML sitemaps are handled and that index expansion is not automatic.

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 tightly packed sentences with no waste. The core behavior is front-loaded, followed by usage guidance, an important limitation, and operational constraints in a 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?

For a two-parameter read-only fetch tool with an output schema, the description covers the essential behavioral context: output shape, non-recursive expansion, and hard limits. Nothing an agent needs in order to invoke it correctly appears to be 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 50%, with the url parameter well documented in the schema and max_entries left without a description. The description adds the 1,000-entry cap, which indirectly clarifies the max_entries upper bound, but it does not explain the parameter's purpose, default behavior, or how truncation is signaled.

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 ('Fetches one uncompressed XML sitemap') and clarifies the two possible outputs: URL entries or child sitemap references. It distinguishes this tool from siblings like inspect_robots and extract_links by positioning it for sitemap-based site structure discovery.

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 use case ('site structure discovery') and an explicit exclusion: sitemap indexes are not recursively expanded, so each child must be called separately. It does not explicitly name alternative tools, but the usage context is clear enough to route the agent correctly.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description goes beyond them with hard operational limits: 512 KiB request, 40 nesting levels, and a 100-error return cap, which materially affects how an agent should size inputs and interpret truncated error lists. It could additionally state what happens on an invalid instance, but the output schema 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?

Three short sentences, front-loaded with the core purpose, followed by usage and then limits. Every sentence carries distinct information with no repetition.

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 needn't be explained, and the description covers purpose, input sizing limits and non-mutation. It is nearly complete; the only minor gap is that it does not hint at how 'instance' is passed or how boolean schemas are treated.

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 0%, so all three parameters rely on the description, which only clarifies the 'draft' parameter by listing the four accepted values that mirror the enum. It adds nothing about 'instance' (which accepts any JSON value) or about the object-or-boolean union accepted for '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 precise verb and resource ('Validates a JSON value against a supplied JSON Schema') and enumerates the supported drafts (4, 7, 2019-09, 2020-12). No sibling in the list does validation, so the tool is unambiguously distinguishable from the fetch/parse/extract 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?

'Use this to verify generated or extracted structured data' gives a concrete use case that ties it to the sibling extraction tools. It does not spell out when-not to use it or name an alternative, but no plausible alternative exists in this toolset.

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