edgegate_trigger_replay

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

Despite no annotations, the description discloses key behaviors: asynchronous verdict delivery, the need to poll edgegate_recorder_status, and the resolution of events without a certified reference to no_reference. It explains the internal logic (replaying against a PASSED gate run and input-matched baseline). It does not mention side effects like whether pending events are removed or idempotency, but for a trigger tool, it is reasonably transparent.

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 three sentences, front-loaded with the primary action. Each sentence adds value: the first explains what the tool does, the second explains async behavior and where to get results, and the third clarifies an edge case. No wasted words or redundant info.

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?

Given the tool's complexity (async replay with edge case handling) and lack of output schema, the description covers the essential aspects: what triggers the replay, what happens after (poll status), and what happens without a reference. It does not describe the immediate return value or whether a job ID is returned, but the instruction to poll status implies this. Overall, it is sufficiently complete for an agent to use correctly.

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 67% (limit and device_id have descriptions; workspace_id has only a format). The description itself does not add parameter-specific details, but the context of 'pending recorded events' helps infer the purpose of limit and device_id. It does not compensate for the missing workspace_id description, but the schema and tool name provide enough context.

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 action: 'Replay pending recorded events against their certified reference... plus the input-matched baseline.' It identifies the resource (pending recorded events), the specific context (certified reference and baseline), and differentiates from sibling tools like edgegate_capture_reference and edgegate_recorder_status by describing the replay trigger and async status retrieval.

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 context for when to use the tool (when pending events need replaying) and points to the sibling tool for status ('poll edgegate_recorder_status'). It does not explicitly state exclusions or alternatives for the replay action itself, but the pointer to status polling and the explanation of no_reference outcomes offer practical guidance.

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