replay_flow

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 does disclose key behaviors: session variable substitution ({{varname}} replacement), regex replacements, and the follow_redirects behavior with a default and purpose. However, it does not explicitly mention that this sends live traffic which could have unintended side effects, nor does it discuss authentication requirements or rate limits. Still, the description provides meaningful behavioral context beyond a simple 'resend' action.

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 well-organized with bold section headers (PREREQUISITE, Session variable substitution, Regex replacements, TYPICAL IDOR WORKFLOW, Args). Each section serves a purpose and builds logically. While it is long, the length is justified by the tool's complexity and the need to explain the substitution and replacement mechanisms. The most critical information (what it does) is front-loaded, and the argument list is at the end.

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 having three parameters and no annotations, the description covers everything needed: purpose, prerequisites, usage context, parameter semantics, and even a concrete workflow example. Since an output schema exists, return-value details are not required. The description is complete enough for an agent to correctly select and invoke this tool without further clarification.

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 has zero description coverage, so the description entirely compensates. The 'Args' section provides clear explanations for all three parameters: flow_id (the captured flow to replay), replacements (a list of objects with regex and replacement), and follow_redirects (with default and purpose). It even gives an example of the replacements format, which is crucial for correct invocation. This is excellent parameter documentation.

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 function: 'Resend a captured HTTP request with optional modifications.' The verb 'resend' is specific and the resource ('captured HTTP request') is well-defined. The analogy to Burp Repeater instantly conveys the tool's nature. It distinguishes itself from sibling tools like 'inspect_flow' (viewing only) and 'send_raw_request' (creating new requests) by focusing on replaying an already-captured flow.

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 an explicit PREREQUISITE (get flow_id from get_traffic_summary or search_traffic), a typical IDOR workflow with exact steps, and mentions when to use the feature (token rotation via session variable substitution). This goes beyond general clarity by giving concrete before-and-after steps, effectively covering 'when to use' and referencing alternatives for acquiring the flow_id.

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