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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly discloses that it runs in the background, returns immediately, auto-skips validation failures, and implicitly signals a poll-able async workflow. The destructive nature of the resetAppData parameter is well documented within the param description, and the disabled-interactive-input limitation surfaces a genuine behavior an agent could otherwise be surprised by. It doesn't detail return format or error behavior, but given zero annotations the description is strong.

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?

Three tight sentences that earn their place: the action and return contract, the alternative-tool disambiguation, and the validation-failure behavior. No filler, no restating of the schema, and the most decision-relevant info (you get an ID back, poll separately) is front-loaded in the first sentence.

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 tool returns a replayId and is part of a multi-tool workflow (flow_replay_start → flow_replay_status/abort/step). The description adequately ties into that workflow by naming the poll tool and explaining the async contract. With no output schema, the description carries the burden of explaining what the caller receives, which it does. It could describe the replayId's other downstream consumers (flow_replay_abort, flow_replay_step) and what the other 3 params do behaviorally, but the core workflow is sufficiently specified.

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%, so the baseline is 3. The description adds value beyond the schema by explaining the orchestration contract (replayId → flow_replay_status poll loop) and gives semantic guidance in resetAppData about when to enable it (enrollment/first-run/logged-out flows) and the destructive consequence. The description enriches the two required params' purpose by framing them as the minimal invocation while the optional params clarify tradeoffs. The main upstream param (recordingId) could reference where recordings come from, but flow_recording_list is already named in 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?

Description uses a specific verb ('Kick off a flow replay in the background') with a clear resource and key behavior (returns replayId immediately). It explicitly distinguishes from the sibling tool flow_recording_replay by noting it runs in background vs. monitoring live, and it clearly names what to pass the result to (flow_replay_status). This is a model example of a purpose that differentiates from alternatives.

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 states when to use this tool ('Use this instead of flow_recording_replay when you want to monitor live or do other work while the replay runs'), naming the exact alternative and the disambiguating condition. Also discloses the behavioral constraint that validation failures are auto-skipped due to MCP lacking interactive input, informing when the tool should NOT be expected to pause for confirmation. This fully satisfies the when/when-not/alternatives requirement.

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