Control run

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

Annotations already flag destructive=true, idempotent=false and openWorld=true; the description goes beyond them by explaining that terminate leaves completed steps in place and that a mismatched eventType silently does nothing — a non-obvious failure mode worth knowing. It does not cover auth/permission needs or what pause does to in-flight steps, keeping it short of a 5.

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-loads the action list, then conditions, then the failure mode and the alternative — a sensible order with no filler. It is dense but long for a single description; the closing rationale about replay is useful but the densest element.

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 destructive, non-idempotent control tool, the description supplies the preconditions (get_run for send_event), the semantics of each action, the silent-failure trap, and the correct alternative tool. Return values are covered by the existing output schema, so nothing an agent needs to invoke correctly 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 80%, so the baseline is 3, and the description adds real meaning: eventType must exactly match an awaitingEvents entry from get_run, and payload is the JSON handed to the waiting node. workflowId/instanceId sourcing (from list_workflows/create_workflow/get_run) is only partly restated, so not a full 5.

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?

Opens with a precise verb+resource ('Act on one in-flight durable run') and enumerates the four supported operations, so the agent immediately knows the scope. The explicit contrast with run_workflow and the absence of step-replay cleanly separates it from the other run tools (get_run, list_runs).

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 per-action conditions ('terminate stops it where it is', 'pause', 'resume') plus an explicit prerequisite for send_event: read get_run first and use one of its awaitingEvents. It also names the alternative for restarting a workflow (run_workflow) and states why replay is not offered.

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