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

Goes well beyond the readOnly/openWorld/idempotent annotations: robots.txt compliance, refusal of private/internal hosts, free-tier quota with shared counters, per-minute rate limit, invalid-input policy, exact error behavior (x402 pay URL, price, chains) and the full return shape. This is exactly the extra 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?

Front-loaded with purpose and sibling routing, and nearly every sentence carries operational value. The pricing/quota sentence is long and slightly over-detailed for a tool description, but it is a single clause and not repeated elsewhere.

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?

No output schema, so the description must and does enumerate the important return fields (risk_score, verdict, flagged, categories, findings with visible/hidden location, hidden_html, page status). It also sets the correct expectation with 'read-only safety signal, not a guarantee'.

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?

Single required parameter with 100% schema description coverage, which already states public absolute http(s) URL, private/loopback refusals and robots.txt behavior. The description adds no additional parameter-level semantics, so the schema-driven 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 ('fetches a public web page and scans... for prompt injection') and explicitly names what it scans (visible text plus hidden HTML segments). It is clearly distinguishable from scan_text and scan_tools, which are named as the alternatives for other input types.

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 frames when to use it ('before your agent browses or summarizes it') and routes the agent to the correct sibling: scan_text if the content is already in hand, scan_tools for MCP tool definitions. No ambiguity about selection.

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