Get a run

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real behavioral context on top: the 30 s wait ceiling, the immediate-return behavior for human-gated states, and the fact that "detailed" exposes raw step input/output/error. The human-gating nuance is exactly the kind of trait an agent cannot infer from annotations or schema.

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 resource and its payload, then the wait semantics, then the mode difference. Dense but no filler sentences; the returns clause slightly duplicates the presence of an output schema, which is the only minor 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?

Covers the hard parts of a polling-get tool: retry policy, human-gated states, and the mode switch. With an output schema present it needn't detail return values, and the remaining gap (error/not-found behavior, how credits are scoped) is minor for this complexity.

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 baseline is 3, but the description adds meaning beyond the schema: it explains that wait:true returns immediately for person-gated runs (the schema only says "wait up to 30 s"), and that detailed adds run title and workers in addition to raw step payloads. That is genuine value over the field descriptions.

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 opens with a specific verb and resource ("Reads one worker run") and enumerates exactly what is returned: status, done flag, steps, reviews, credits, answer. The singular "one worker run" also distinguishes it from the sibling heliyos_runs_list, so an agent can pick without opening either schema.

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?

Strong conditional guidance for the polling loop: call again with wait:true while done is false, but do NOT poll when the run is awaiting_approval/paused/waiting/scheduled because it will return at once and only moves when a person acts. It gives no explicit guidance on when to prefer heliyos_runs_list or heliyos_tasks_get instead, which keeps it short of a 5.

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