site-audit

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 valuable behavioral context beyond annotations: the exact cost ($0.075 USDC per successful audit), the payment mechanism (x402 v2), the fact that payment and result are exchanged at a specific GET URL, and the lack of required account/API key. This goes beyond simple read-only semantics.

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

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

The description is four sentences, each providing distinct information: pricing, definition, handoff details, and authentication surface. It is not overly verbose, though the pricing and handoff details could potentially be condensed. Overall, it is well-structured and front-loads the critical paid-capability warning, making it easy 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 tool with a paid step and a handoff mechanism, the description covers the essential operational context: what it does, how the handoff works, cost, and authentication requirements. It does not explain the output schema, but that is provided separately. Given the rich annotations and output schema, the description is sufficiently complete, though it could mention potential failure modes or rate limits.

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%, and the description does not explicitly elaborate on the parameters beyond mentioning 'depth=quick' in the example URL. The URL parameter is already described in the schema as 'A publicly reachable HTTP or HTTPS target,' and depth has an enum with only 'quick.' However, the description does not add meaningful nuance about how to choose or use these parameters; thus it is adequate but not enriched.

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

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

The description clearly states the specific action: it 'passively assesses how well a public website or service can be discovered, understood, invoked, and—where explicitly applicable—paid by agents.' This is a specific verb+resource combination that distinguishes it from siblings like audit_website_preview or extract_page_markdown. It also explains the return value (canonical x402 HTTP handoff), reinforcing its unique purpose.

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

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

The description provides clear context for use by stating it is a paid capability, requires no API key, and returns a handoff for payment. It implies when to use it (to assess agent-readiness of a website) without explicitly naming alternatives or exclusions. Since no direct comparison to siblings is given, it falls short of a 5 but is well above a 3.

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 (readOnly, idempotent, non-destructive), the description adds crucial behavioral details: the 1-per-day-per-IP quota, shared quota for hosted agents, and the fact that it only audits a single page without crawling or rendering. This transparency about limitations and rate limits goes well beyond what annotations 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 description is long but every sentence carries relevant information: headline, capabilities, limitations, quota note, and alternative endpoint. It is front-loaded with the key purpose and structured logically, though slightly dense as a single paragraph. It earns its length without unnecessary fluff.

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

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

The description is thorough for a complex tool: it explains the preview nature, the exact scope (one page), what is excluded, the quota mechanism, and even the production alternative with pricing and protocol. With an output schema present, return values need no description. This is a complete and self-contained description.

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% for the single 'url' parameter, and the schema already describes it as a publicly reachable HTTP/HTTPS page. The description only mentions 'one public page,' which adds no new semantic meaning beyond the schema. Baseline 3 is appropriate since 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 clearly states the tool 'Runs a fast Quick Intelligence Audit of one public page' and enumerates specific checks like fetch timing, SEO, and security headers. It also distinguishes itself from sibling tools by explicitly listing what it does not do (no crawling, JS rendering, etc.), making its purpose unambiguous.

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

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

The description provides clear usage context: it is a free preview with a daily quota per IP, intended as a sample not capacity. It also directs users to the production endpoint for real use. However, it does not explicitly compare to sibling tools like audit_agent_readiness, so differentiation from alternatives is slightly less explicit.

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 (readOnly, idempotent), the description discloses key behavioral traits: it is a paid capability, validates the target, and returns an x402 HTTP handoff rather than the result directly. It also states that payment and result are exchanged via a specific endpoint, and that no account or API key is required. No contradiction with annotations.

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

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

The description is packed with essential information across five sentences, each serving a distinct purpose: cost, functionality, scope limits, handoff mechanism, and auth requirements. It is front-loaded with the most critical operational detail (paid capability) and contains 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?

Given the tool's complexity (paid, x402 handoff, single-page) and the presence of an output schema, the description fully covers what the agent needs to know: the result format, the limitation on crawling/JS, the payment workflow, and authentication. It is complete enough to invoke correctly and follow up on the handoff.

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

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

The input schema provides complete coverage of the 'url' parameter with a clear description ('A publicly reachable HTTP or HTTPS page'). The description adds no new parameter-specific meaning beyond confirming 'public page' and validation behavior, which does not elevate it above the baseline established for high schema coverage.

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

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

The description explicitly states the verb and resource: 'Fetches one public page and returns its main content as clean Markdown plus title, description, outbound links, and word count.' This clearly differentiates it from siblings like 'extract_structured_data' or 'link_map' by specifying the output format and single-page scope.

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 provides explicit when-to-use ('Single page only') and when-not-to-use ('no crawling or JavaScript rendering') guidance. The cost and lack of API key requirement also inform the decision. While it doesn't name alternative tools, the constraints clearly signal that this is for one-off page extractions, not bulk or dynamic content.

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 the $0.08 fee, x402 protocol handoff, re-validation before return, 422 status for non-conforming output, 8000-character truncation, and no-auth requirement. This exceeds what annotations alone convey.

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

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

The description is dense but organized, front-loading the cost warning and then systematically covering behavior, constraints, and handoff details. It is slightly long, but each sentence adds essential 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 the tool's complexity (payment, x402 handoff, validation, truncation), the description fully covers the operational workflow, endpoint, auth, and limitations. The presence of an output schema means return values need not be elaborated further.

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%, providing a baseline of 3. The description adds crucial meaning: the schema parameter is optional on the MCP call but required on the POST, and it must be self-contained without $ref. This elevates semantic clarity beyond the schema.

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

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

The description explicitly states the action and resource: 'Fetches one public page and returns JSON fields extracted by an LLM against your own JSON Schema.' It also distinguishes itself from siblings by noting 'Single page only — no crawling or JavaScript rendering.'

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

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

The description provides clear usage context: it is a paid capability with a specific POST endpoint, works on a single page, and excludes crawling/JS rendering. It does not explicitly name alternative sibling tools, so it falls short of 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?

Despite annotations indicating read-only/idempotent behavior, the description adds critical context: the paid capability ($0.003 USDC), the 422 error behavior, the x402 handoff, and that no API key is required. This significantly exceeds what annotations alone convey and contains no contradictions.

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

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

The description is compact yet information-dense, front-loaded with the essential payment warning. Every sentence adds distinct value: cost, function, error behavior, handoff mechanics, and authentication requirements. No wasted words.

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

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

Given the tool's complexity (payment, handoff, error semantics), the description is remarkably complete. It covers all critical aspects: what the tool does, limitations (50 items), failure mode (422), payment flow (x402), endpoint URL, and lack of auth. The presence of an output schema reduces the need to describe return structure.

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%, providing a baseline of 3. The description adds value by specifying supported formats (RSS 2.0, Atom, JSON Feed), reinforcing 'public' reachability, and explaining the consequence of non-feed URLs. These details go beyond the schema's simple 'publicly reachable HTTP or HTTPS feed URL'.

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

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

The description clearly states the tool parses public feed URLs (RSS, Atom, JSON Feed) into normalized JSON with feed metadata and up to 50 items. It uses a specific verb ('Parses') and identifies the resource, distinguishing it from the sibling web-scraping/audit tools.

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

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

The description implies usage context by listing supported feed types and explicitly states non-feed targets return 422, serving as a when-not-to-use signal. It does not explicitly name alternative tools, but the scope is clear enough for selection.

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

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

The description adds significant behavioral context beyond the annotations (readOnly, idempotent, non-destructive). It discloses the cost ($0.003 USDC per success), the two-step workflow (MCP returns an x402 handoff, actual result exchanged via HTTP), and that no account or API key is required. No contradiction with annotations.

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

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

The description is four sentences, each earning its place: cost warning first, core functionality, workflow, and auth status. It is front-loaded with the most important caveat (paid capability) and contains 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?

The description covers function, constraints (up to 200 links), cost, the handoff workflow, and no-auth requirement. Given that an output schema exists, return values need not be described. It lacks failure modes or edge cases, but is sufficiently complete for an agent to invoke correctly.

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

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

The schema already fully documents the single parameter 'url' as 'A publicly reachable HTTP or HTTPS page.' The description adds 'public HTML page' and 'validates the target,' but these do not materially enhance what is already in the schema. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool's action and resource: 'Maps one public HTML page's links into a categorized link map' with specific categories and counts. It also distinguishes itself from siblings like extract_page_markdown and extract_structured_data by focusing on link mapping.

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 usage (when you need a categorized link map of a page) but does not explicitly state when to use this tool versus siblings or mention any exclusions. No alternative tools are referenced, so guidance is only implied.

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

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

The description goes far beyond annotations by disclosing the paid nature ($0.033 per success), the 422 error for non-HTML targets, and the critical workflow that the MCP call returns an x402 HTTP handoff rather than the actual summary. It also specifies the API endpoint and that no account/API key is required. No contradiction with readOnlyHint or idempotentHint.

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 dense and front-loaded with the payment warning, then flows logically into purpose, behavior, and API details. Every sentence carries necessary information, though it is longer than typical tool descriptions due to the complex two-phase workflow.

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 paid, two-step tool with handoff, the description is exceptionally complete: it covers payment, error behavior, the exact API endpoint, request format, authentication, and the handoff semantics. Combined with the presence of an output schema, an agent has everything needed to invoke and complete the operation.

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?

Although the schema covers both parameters at 100%, the description adds value by explaining the focus parameter as a 'steering prompt' with an example ('pricing plans') and showing how url and focus map to GET/POST request formats. This provides practical usage context beyond the schema's brief descriptions.

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

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

The description clearly states the tool summarizes one public HTML page and lists the structured output fields (title, summary, key_facts, entities, word_count). It uses a specific verb and resource, and the emphasis on structured summary distinguishes it from sibling tools like extract_page_markdown or extract_structured_data.

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 usage for summarization and mentions the optional focus steering prompt, but it does not explicitly state when to use this tool over alternatives or when not to use it. No sibling comparisons or exclusions are provided.

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