InjectScan

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

Annotations cover the safety profile, but the description adds substantial context beyond them: what it detects, free-tier limits (30/day per IP shared across all three tools, 10/min, invalid input not counted), and exactly what happens on quota exhaustion (error with x402 pay URL, price, chains). It also candidly scopes the result as a 'safety signal, not a guarantee.'

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 alternative routing before limits and pricing. It is dense and somewhat long, but nearly every clause (detection categories, rate limits, return fields) carries information an agent needs; minor trimming of the pricing detail was possible.

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 tool with no output schema, the description enumerates the return shape (risk_score, verdict, flagged, categories, findings, free_tier usage) and clarifies truncation semantics. An agent has everything needed to call it and interpret the result.

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% and the schema already explains the character range, truncation behavior, and offset semantics. The description reinforces the 100000-character limit but adds little the schema doesn't already say, so it sits at the baseline for a fully documented single-parameter 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 ('scans untrusted text for prompt injection') and enumerates the exact content classes it covers. It explicitly distinguishes itself from both siblings, telling the agent to use scan_url for links and scan_tools for MCP definitions.

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 when-to-use guidance ('before your agent reads or acts on it') and names both alternatives with the condition that selects each: scan_url when you only have a link, scan_tools for tool definitions. Nothing is left to inference.

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

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

Annotations already declare readOnly/openWorld=false/idempotent, but the description adds substantial context beyond them: a 30 calls/day free tier shared across all three scan tools, a 10/min cap, invalid input not counted, and a documented x402 fallback with price, chains and URL. It also discloses the return payload fields and honestly frames output as a safety signal, not a guarantee. The only thing left implicit is latency/behavior on partial failures.

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

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

Front-loaded with purpose, then alternatives, then limits, then return shape — a sensible information order. It is dense, however: rate-limit, pricing and return-shape details are packed into one long paragraph where a few of the clauses (invalid-input accounting, full URL) could be trimmed.

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, no-output-schema tool, the description covers everything an agent needs: what is scanned, limits, failure/payment path, response fields and the caveat that the verdict is not a guarantee. Nothing actionable is missing.

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

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

Schema coverage is 100% and the schema description already explains the 1-100 object shape plus the name/description/inputSchema key handling. The description's 'Up to 100 tools per call' largely restates the schema's '1-100' bound, adding no format or edge-case meaning. Baseline 3 is appropriate 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?

States a specific verb and resource — checks MCP/function-calling tool definitions for tool poisoning — and enumerates the vectors it looks for (hidden instructions, exfiltration, name/description/schema hijacks). It also explicitly separates itself from scan_text and scan_url, so an agent can route 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 the exact decision rule: use this on tool definitions before installing or calling them, use scan_text for ordinary content, scan_url for web pages. Alternatives and selection conditions are both named, 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 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.