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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description goes well beyond them: it enumerates per-run-type effects, names irreversible actions (Slack messages that cannot be taken back), discloses credit spend per run type, and specifies the exact reversal path via reverse_audit_event. This is exactly the extra context that turns a destructive write into a predictable one.

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-loaded with the action and its risk posture, and the long run-type enumeration is dense and information-bearing rather than padding. It runs slightly long and the mid-sentence catalogue of run types could be compressed, but almost every clause earns its place.

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 no output schema, the description explains the return behavior fully (returns as soon as work is launched, not on completion) and routes the agent to get_run for status and the funnel for results. For a high-blast-radius action tool, nothing an agent needs to call it 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 description coverage is 100%, so both run_id and connection_id are already documented by the schema, including the "must already exist" and "call list_crm_connections first" hints. The description adds no parameter-level detail beyond what structured fields provide, so the baseline 3 applies.

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?

States a specific verb+resource ("Start a created run") and explicitly distinguishes itself from the surrounding lifecycle with "THIS IS THE STEP THAT ACTS." An agent can separate it from the create_*_run siblings (which only create) and get_run (which reads) without opening schemas.

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 explicit when-to-use (after creating a run, it must already exist), what to do afterward (poll get_run until terminal, then read the funnel), and names alternatives for reversal (reverse_audit_event). It also flags the propose/queue disposition case where writes are held for a person rather than executed.

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