MAD Synapse · Web & Research

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantive traits beyond them: 1-request-per-3-second pacing, caching behavior, the $0.001/call price with 10 free/day and x402 payment fallback, and error semantics (isError on invalid input/upstream failure, not charged). This is exactly the extra context an agent needs 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 clause, and each subsequent sentence covers a distinct concern (query syntax, pacing/caching, pricing, errors) with no filler. Dense but every sentence earns its place.

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

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

An output schema exists so return values need not be re-explained, and the description still sketches the payload (abstracts, authors, dates, PDF links). Pricing, rate limits, caching, and error behavior are all covered, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds arXiv query-syntax semantics beyond the schema's examples (ti:, au:, abs:, cat:cs.AI, AND/OR), clarifying what the required 'query' string actually accepts. Sort and limit are already 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 resource ('Search arXiv research papers') plus scope (keywords, author, category) and sort modes. It is clearly distinguishable from siblings like book_search, hn_search, wiki, and doi_lookup without opening 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 clear context for when this tool applies (arXiv academic literature) and notes the two sort intents, but never names an alternative or a when-not condition (e.g. vs. doi_lookup for DOI resolution or web_read for arbitrary pages). Clear context, no explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: per-call pricing, a free daily quota, an x402 payment-required path, and the fact that invalid-input/upstream errors return isError and are not charged.

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 return fields are front-loaded, followed by source, cost, and error behavior. Three dense sentences with no filler, though the pricing/error sentence is long and could be split for readability.

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 explanation is not strictly required, yet the description still sketches the response fields. Cost model, quota, payment fallback, and error semantics are all covered, leaving nothing an agent needs before calling.

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% (query and limit both documented, including range and default), so the schema carries the parameter burden and baseline 3 applies. The description only marginally adds 'subject' as a query key beyond the schema's 'title, author or ISBN', with no syntax details for ISBN formatting.

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

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

The description names a specific verb and resource ('Find books by title, author, subject or ISBN') and enumerates the returnable fields, so an agent can distinguish it from sibling search tools like arxiv_search, doi_lookup, or wiki without opening the 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?

Scope is clear from the enumerated search keys and the named data source (Open Library), which implies usage, but there is no explicit when-to-use guidance or routing to alternatives such as arxiv_search or wiki for non-book queries. The pricing/error notes describe behavior rather than when to pick this tool.

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

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

Annotations cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), and the description goes well beyond them: live querying against named public resolvers (Cloudflare, Google, Quad9), the exact email grading rules (SPF ending in -all/~all, DMARC p=quarantine/reject), pricing (free), and error semantics (isError with a message, not charged). This is exactly the behavioral context 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?

Front-loaded with the core capability, then cleanly delimited sections for resolvers, grading, usage, price, and errors. Dense but every clause carries information; 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 shape needn't be described, and the description otherwise fully equips an agent: what it returns, how email is graded, where it queries, what it costs, and how failures manifest. 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?

With a single parameter at 100% schema coverage, the schema already documents the 'domain without scheme' format. The description adds no parameter-level syntax or constraints beyond what the schema provides, so the 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+resource (lookup all DNS records for a domain) and enumerates the record types returned, plus the extra value-add (SPF/DMARC graded). It explicitly distinguishes itself from siblings by naming domain_whois and tls_check, so an agent can route correctly without opening 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?

Provides an explicit 'When to use' clause plus concrete alternatives with their selecting conditions: domain_whois for ownership dates, tls_check for certificates. Both the positive case and the exclusion boundaries are 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 cover safety (readOnly/idempotent/non-destructive), but the description adds materially more: upstream source (Crossref, 150M+ works), pricing and free-tier quota ($0.001/call, 10 free/day, x402 payment-required result), and error semantics (isError on invalid input or upstream failure, not charged). These are exactly the operational traits 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?

Front-loaded with the core action and return fields, then labeled 'When to use / Price / Errors' sections. Dense and information-rich with very little waste, though the field enumeration plus three trailing clauses make it longer than strictly necessary.

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 not be documented, yet the description still previews them; combined with mode selection, billing, and failure behavior, 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 adds real semantic value beyond the schema by framing doi and query as two mutually exclusive entry modes and by stating that search mode returns 'the top matches', which contextualizes the limit parameter's purpose.

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: 'Resolve a DOI — or search a paper title — to full citation metadata', followed by an enumeration of the exact fields returned. It also explicitly carves itself apart from the nearest sibling ('to search preprints by topic use arxiv_search'), so an agent can route 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?

Contains an explicit 'When to use' clause plus a named alternative and the condition selecting it (known paper vs. topic discovery via arxiv_search). Both operating modes (DOI resolve vs. title/author search) are stated with their triggers.

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 readOnly/openWorld/idempotent annotations: it discloses the data source (RDAP with rdap.org bootstrap), the availability heuristic (no RDAP record + no DNS), the young-domain flagging rule (<30 days), pricing ($0.002/call, 10 free/day, x402 payment-required result), and error behavior (isError on invalid input/upstream failure, not charged). This is unusually 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?

Dense but front-loaded: the return payload leads, followed by source, heuristic, usage, pricing, and error handling. Every sentence carries distinct information with no filler.

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

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

Despite an output schema existing, the description fully covers what an agent needs: the input format, the availability semantics, the freshness flagging, cost, and error handling. Nothing required 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?

With a single parameter at 100% schema description coverage, the schema already documents the required 'domain' input including format guidance. The description adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Who registered a domain') and enumerates the returned fields (registrar, creation/expiry dates, status locks, nameservers, availability). It explicitly differentiates itself from dns_lookup, so an agent can distinguish it from siblings without opening the 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?

Contains an explicit 'When to use' clause scoped to registration and expiry, and names the alternative ('for DNS records use dns_lookup'). The condition that selects the sibling is spelled out, leaving nothing 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?

Goes well past the readOnly/idempotent/openWorld annotations by disclosing the verification method (no mail sent, no SMTP probing), the source of the verdict (live MX lookup plus a ~100k disposable-domain list), billing mechanics ($0.001/call, 10 free/day, x402 payment-required result), and error handling (isError on invalid input or upstream failure, not charged).

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 core question and the list of checks, then dense supplementary detail on pricing and errors. Everything is relevant, though the billing/error sentences are somewhat packed and could be tightened.

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 not be described. Between method, verdict source, cost model, and error semantics, the description gives an agent everything needed to decide whether and how to call it.

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

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

Schema coverage is 100% with a single required parameter, and the 'no mail is sent' note is already echoed in the schema's own description. The description adds no format, syntax, or constraint detail beyond what structured data provides, 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?

Opens with a concrete question the tool answers ('Will this email address work?') and enumerates exactly what is evaluated: syntax, MX records, disposable providers, role addresses, free-mail providers. This is clearly distinguishable from siblings like dns_lookup, address_check, or http_probe.

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

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

The description implies when to use it (validating deliverability without sending mail) and rules out the SMTP-probing alternative that would burn server reputation. However, it never names a sibling tool or states an explicit when-not-to-use condition, leaving the agent to infer usage from context.

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 openWorld. Beyond those, the description adds genuinely useful context: the $0.002/call pricing with 10 free/day and x402 payment options on overage, plus error behavior (isError with a message, not charged on failure). This is substantive operational detail the annotations do not provide.

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

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

The definition is front-loaded with the returned fields and the health-judgment purpose, then layers in pricing and error semantics. The long field enumeration is dense but informative and earns its place. Minor redundancy in the trailing pricing/error sentences 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-value explanation is rightly omitted. With rich annotations, a single fully-documented parameter, and added coverage of pricing, activity semantics, and error behavior, the description is nearly complete. Only the lack of alternative-tool routing leaves a small gap.

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

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

Schema description coverage is 100% and the single 'repo' parameter is fully documented in the schema ('owner/name or a github.com URL'). The description adds no additional parameter syntax beyond noting data comes 'From the GitHub REST API.' This is the baseline 3 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?

The description names the specific resource (a GitHub repository) and enumerates exactly what it returns (stars, forks, open issues, last commit, latest release, license, languages, contributors, archived), plus the underlying goal ('is it alive and trustworthy?'). An agent immediately understands the scope without opening 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?

It gives clear usage context: the 'activity' field 'summarizes days since last push and last release so an agent can judge whether a project is maintained.' This tells the agent when the tool is appropriate (assessing project health). However, it names no alternative tool or exclusions, so it stops short of full when/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 readOnly/idempotent/no-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful context beyond the schema: pay-per-call pricing with 10 free/day, the payment-required result shape, and that failed calls (isError) are not charged. It doesn't cover rate limits or latency, but this is well above the annotation bar.

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

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

A single tight paragraph that front-loads purpose before capability details, then pricing and error semantics at the tail. Operationally important facts are packed densely without filler, though the return-field list is somewhat redundant given the output schema exists.

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 search tool with a full output schema and complete parameter documentation, everything an agent needs is present: what it searches, how to narrow results, cost per call, free tier, and failure behavior. Nothing material 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 every parameter (days, sort, type, limit, query, min_points) is already documented, and defaults/ranges are explicit. The description restates the filtering dimensions but adds no syntax or format detail beyond the schema; the baseline 3 applies. It omits 'limit' entirely.

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 ('Search Hacker News stories and comments by keyword') plus the data source ('Algolia's official HN search'). An agent can distinguish it instantly from unrelated siblings like web_read or github_repo, and it names the sortable/filterable dimensions up front.

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 clear usage context ('what developers are saying about anything') and the conditions that shape a call (time window, minimum points, relevance vs date). It never names an alternative tool or states a when-not-to-use condition, so it stops short of full routing guidance.

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

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

Adds substantial context beyond annotations: it performs one real GET from the tool's server, details which headers contribute to the security grade, states exact pricing ($0.001 per call, 10 free/day, then x402 payment), and explains error returns and charging behavior. Annotations already cover read-only/open-world/idempotent/non-destructive traits, and the description enriches that profile without contradicting it.

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

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

The description is front-loaded with what the tool returns before moving to usage, pricing, and errors. It packs many details into a dense first sentence, which is efficient but slightly run-on. Overall every sentence adds useful information, with little waste.

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 existing output schema, the description need not explain return values, and it covers the remaining agent needs: scope, alternatives, pricing, and error semantics. For a one-parameter HTTP probing tool with a rich output schema, this is complete enough for correct selection and invocation.

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

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

There is one parameter and schema description coverage is 100%, so the schema already documents the 'url' input. The description adds no extra syntax or format detail for the URL parameter beyond what the schema provides. Baseline 3 is appropriate when the schema fully handles parameter 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?

States a specific verb and resource: probe a site's availability and serving characteristics (status, redirect chain, timings, server, CDN, caching, compression, security headers). It distinguishes itself from sibling web_read by explicitly pointing to web_read for page content. An agent can tell what it does and does not need to open the 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 says 'When to use: For availability, status and timings; for page content use web_read.' This names the condition and the alternative, leaving no ambiguity. It also covers cost and error behavior, giving full invocation context.

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/openWorld, so the bar is lower, yet the description adds real behavioral context beyond them: pricing ($0.001/call, 10 free/day, x402 payment-required result), error semantics (isError with message, not charged for invalid input/upstream failure), and data-quality flags (deprecated, no release in 2+ years). It does not describe response shape, 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?

Front-loaded with capability, then what it returns, then usage routing, then cost and error behavior — a sensible priority order. It is somewhat dense and the ecosystem list is repeated from the schema, but nearly every clause carries actionable 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 a simple 2-param read tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: scope across three registries, staleness/deprecation flagging, pricing and payment flow, failure semantics, and an alternative tool for vulnerability checks.

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 both parameters (name, ecosystem enum with default) are fully documented in the schema, so the baseline is 3. The description restates the ecosystems and confirms registry sourcing (plus npm/pypistats download counts), which adds only marginal meaning over 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 ('Any npm, PyPI or crates.io package') and enumerates exactly what is returned (version, release date, license, downloads, maintainers, repo, dependency count, deprecation). It also names a sibling (vuln_check) it must not be confused with, so an agent can disambiguate without opening schemas.

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

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

Explicit 'When to use' line states the use case (package metadata for picking/vetting dependencies) and routes a different use case to a named alternative, vuln_check, with the server location. Both the when and the when-not are 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses pricing ($0.001/call, 10 free/day, x402 payment-required result), error behavior (isError, not charged), matching semantics (longest match, Allow beats Disallow, wildcards), and the missing-robots.txt default.

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 core question, then capabilities, then semantics, then pricing, then errors. Every sentence carries operational value with no filler.

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

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

An output schema exists, so return values need no explanation, and the description covers pricing, error behavior, and matching rules. Nothing an agent needs to invoke 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 both parameters are already documented (url as absolute URL, user_agent with default). The description adds the rule-evaluation semantics ("for any user-agent") but no format or syntax detail beyond the schema, so 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 specific verb+resource: checks a URL against robots.txt, lists sitemaps/crawl-delay, and reports AI-crawler blocking. This is clearly distinguishable from siblings like http_probe, web_meta, or dns_lookup.

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?

"May I crawl this?" frames the usage context precisely and the described capabilities imply when it's the right tool. It does not, however, explicitly name alternatives or state when not to use it (e.g., versus a generic http_probe).

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, openWorld, non-destructive), and the description goes well beyond them: it discloses cost ($0.001/call, 10 free/day, x402 payment-required result), error semantics (isError with a message for invalid input or upstream failure, and explicitly not charged), and the alerting thresholds (< 14 days, expired, untrusted, name-mismatch).

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 resource and its returned fields, then escalation details, pricing and error behavior, each sentence carrying distinct information. The opening field list is dense, but nothing is redundant and the ordering is sensible for an agent scanning for cost and failure modes.

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, yet the description still outlines the certificate surface and adds the details an agent most needs for decision-making: cost model, free tier, payment fallback, and error/charging behavior. For a two-parameter read-only tool, nothing material 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% for both parameters, so the schema already documents 'host' (hostname without scheme or path) and 'port' (default 443, range). The description adds only the 'live handshake' framing, which clarifies that host must be resolvable and port reachable, but no syntax or format detail beyond the schema. Baseline 3 applies 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?

The description states a specific verb+resource (inspect a site's live TLS certificate) and enumerates exactly what it returns (issuer, validity, days to expiry, SANs, protocol, cipher, chain, browser trust). It is clearly distinguishable from adjacent siblings such as dns_lookup, domain_whois, http_probe and robots_check, which do not perform a TLS handshake.

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?

Usage context is implied ('Live TLS handshake to the host', flags for expired/expiring/untrusted/name-mismatch certificates), so an agent can infer when the tool is relevant. However, it never names an alternative (e.g. domain_whois, http_probe, vuln_check) or states when NOT to use it, so routing between siblings 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?

Goes well beyond the annotations (which already cover read-only/idempotent/open-world) by disclosing the pricing model ($0.001/call, 10 free/day, x402 payment-required result), the error contract (isError with a message for invalid input or upstream failure, uncharged), and the specific diagnostic flags it raises (missing og:image, missing description, non-absolute image URLs).

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-loads the resource contents, then usage, then pricing/errors, with no filler sentences. It is on the long side for a one-parameter tool, but every clause (flags, price, error behavior) carries information an agent would otherwise lack.

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 not be explained, and the description still covers routing, cost, error handling, and the problem-detection behavior. An agent has everything needed to call this correctly and interpret a failure.

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

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

The single url parameter is fully documented in the schema ('Absolute http(s) URL of the page') at 100% coverage, and the description's statement that it operates on 'a page' is consistent but adds no new constraint or format detail. Baseline 3 is appropriate when the schema carries the parameter 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?

States a concrete resource and enumerates exactly what it returns: title, description, OpenGraph/Twitter card, canonical, favicon, language, feeds, JSON-LD, headings, plus link-preview problem flags. It also explicitly separates itself from the nearest sibling ('for the article text use web_read').

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?

Names the concrete use cases (link previews, SEO/social card checks, feed/structured-data discovery) and gives an explicit routing rule versus web_read. Nothing about when to pick this tool 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/openWorld/idempotent/non-destructive, yet the description adds materially more: redirects are followed, public internet only, JS-only pages fall back to server HTML (no headless browser), PDFs are text-converted, cost is $0.002/call with 10 free/day and x402 payment on exhaustion, and errors return isError without charging. These are behaviors 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?

Front-loaded with the input→output contract, then capabilities, then limitations, then routing, then cost and error semantics. Every sentence carries a distinct fact (extraction engine, JS limitation, price, refund-on-error); none are 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 needn't be explained, yet the description still summarizes what comes back. For a 3-param read tool with rich annotations, the description covers scope, limits, failure modes, and pricing with nothing an agent needs left out.

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 min/max/default for max_chars and the link-list behavior of include_links are already documented. The description's only added semantic is the usage hint 'Use max_chars to bound the output,' which is directionally useful but not deep enough to exceed the baseline for a fully documented 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 transformation ('Any public URL → clean readable markdown') plus the exact output bundle (title, author, date, word count, links), and names the extraction mechanism (Mozilla Readability). It is immediately distinguishable from web_meta and http_probe, which are named in the same description.

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?

Contains an explicit 'When to use' clause and routes to alternatives by condition: 'for its metadata only use web_meta; for uptime/redirects use http_probe.' No inference required from the agent.

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

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

Annotations already declare the safe, idempotent, open-world read profile, but the description adds materially more: full=true returns plain text with sections kept and truncation by max_chars, disambiguation pages are flagged with alternatives, the call is free, and errors surface as isError without being charged. That is unusually rich behavioral disclosure.

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 core behavior and every sentence carries information (output shape, truncation, disambiguation, when-to-use, cost, errors). "Search + REST summary from Wikipedia" is mildly implementation-flavored filler, but overall it is tight.

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 4-parameter lookup with an output schema, the description covers everything an agent needs to call it correctly: language, summary vs. full text, truncation limit, disambiguation handling, error semantics, and cost. No meaningful gaps remain.

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 still adds meaning by explaining that full returns plain text (sections preserved) and that max_chars caps that output, clarifying the interaction between the two parameters. It adds little for query or lang 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?

Names a specific resource (Wikipedia articles) and the concrete actions/results: search a topic, get the best article's summary, description, thumbnail and link, or the full text. It also distinguishes itself from sibling retrieval tools by calling out paper-oriented alternatives.

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?

"When to use: For encyclopedic topics; for papers use arxiv_search or doi_lookup" gives an explicit condition and routes the agent to named alternatives. The full vs. summary choice is also framed with its cost in output size.

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