generate_ssrf_payload

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

No annotations are provided, so the description carries the full burden. It discloses authorized use and that local_bypass_examples cannot be confirmed, but it doesn't describe the output structure, whether the tool creates a webhook if none exists, or any side effects like logging or rate limits. This is a security-sensitive tool, so more behavioral context is needed.

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 brief and front-loaded with the main action. The multi-line structure with bullet points is clear. No wasted words, but the paragraph break after the first sentence is odd. Still, it's concise and scannable.

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?

There is an output schema, so return format is covered. The tool has 4 parameters, 4 siblings, and no annotations. The description explains the core purpose, acceptable use, and a key limitation (local_bypass_examples not confirmable). However, it lacks context on how to use the generated URLs (e.g., where to insert them) and what the output looks like without an example, but that is mitigated by the output schema.

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 low (25%), with only webhook_token having a description. The description mentions 'local_bypass_examples' which is not a parameter, but it doesn't explain identifier, include_ip, or include_dns beyond their names. Includes that they are booleans controlling IP/DNS payloads is inferrable but not explicit. However, the description does indicate that include_ip and include_dns relate to payload construction, so partial value.

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 generates SSRF callback URLs that ping a webhook. It distinguishes from siblings by naming check_for_callbacks as a companion for confirming hits, and noting local_bypass_examples cannot be confirmed, but it doesn't explicitly contrast with other generation tools like generate_xss_callback.

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 clear usage guidance: use only on authorized systems, not for sign-up email, and confirms hits with check_for_callbacks. It doesn't mention what to do if not authorized or alternatives like generate_xss_callback, but the primary conditions are well stated.

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