opencode_wait

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description meaningfully adds the cancellation behavior: cancelling this wait only stops observation, not the underlying job, and job_cancel or session_abort are required to actually stop OpenCode. It also discloses the possible return statuses and resumable timeouts. This is useful behavioral context beyond the annotations, though it does not detail polling/connection mechanics.

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?

Two sentences deliver the core purpose, return behavior, and the cancellation caveat with zero filler. The most important action ('Wait for a session or durable job') is front-loaded, and the follow-up sentence adds the critical distinction between stopping observation and stopping the work.

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 tool with six parameters, full schema coverage, an output schema, and read-only/idempotent annotations, the description is complete enough. It explains what the tool returns, how cancellation behaves, and points to the correct tools for stopping work. 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%, with every parameter (jobId, directory, messageId, sessionId, pollIntervalMs, timeoutSeconds) already documented in the input schema. The description reinforces the timeout is resumable and references jobId indirectly, but it does not add substantive parameter semantics beyond the schema. Baseline 3 is appropriate given the schema carries the parameter burden.

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: 'Wait for a session or durable job.' It further clarifies the tool's outcome by enumerating the possible return states (completed, failed, input_required, resumable timeout) and distinguishes waiting from stopping work by pointing to job_cancel/session_abort. An agent can immediately tell this is a blocking observation tool rather than a job status or cancellation tool.

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?

The description clearly frames when to use the tool: when you want to wait for a session or durable job to reach a terminal state. It also gives an explicit alternative for stopping OpenCode ('use job_cancel or session_abort'), which helps avoid misuse. It does not explicitly contrast with sibling tools like opencode_events_poll or opencode_job_get, so it stops 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.