gc_run

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

With no annotations provided, the description carries the transparency burden. It discloses some behavioral traits (non-SSE history read vs SSE live tail, events collect until terminal or timeout), which is helpful. However, it doesn't disclose what 'abort' really does, error conditions, auth requirements, or side effects of the control action — meaningful gaps for an operator-control tool.

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 compact and well-structured with an intro line plus three short bullets. Every sentence earns its place, and the action names map directly to the enum values, making navigation effortless. Zero waste.

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 description does a good job covering the three-action surface and mapping parameters to actions. However, with no output schema and no annotations, it doesn't describe return shape, error behavior, or the semantics of seq-based event history, leaving the agent somewhat under-informed about what to expect from each call.

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 100%, so the schema already explains all 8 parameters. The description adds some multi-action context by noting which params apply to which action (since for events/watch, timeout/heartbeat for watch, reason/control_action for control). This maps parameters to actions usefully but doesn't go deep on format or behavior beyond 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?

The description clearly states it handles 'Observable run control and event history' with three distinct actions (events, control, watch), each briefly explained. It's specific about the resource (run) and the operations, and the compact bullet format distinguishes the three sub-modes from each other. Slight downgrade because the sub-actions within one tool make the overall purpose somewhat composite rather than singular.

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?

Each action has a one-line usage context: events is a 'non-SSE history read', watch is 'SSE live tail' collecting until terminal or timeout, control is operator abort. This distinguishes when each sub-action applies, though it doesn't explicitly tell when to prefer gc_run over siblings like gc_timeline or gc_workflow_watch, which could overlap.

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