opencode_inspect

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

With no annotations provided, the description carries the full burden and largely meets it: it discloses the one-shot, non-polling nature and frames the tool as a safe read-only diagnostic. It doesn't explicitly state the NULL session_id behavior or error case for nonexistent sessions, but the core behavioral profile (non-blocking, diagnostic-only, forbidden for monitoring) is well disclosed.

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?

Three sentences, each functional: the first defines scope, the second forbids polling with rationale, the third specifies allowed use cases. The most important trait (DIAGNOSTIC ONLY) is front-loaded. Slightly long but no wasted words.

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?

An output schema exists, so return-value explanation is unnecessary. The description covers purpose, usage constraints, and behavioral traits thoroughly. The main missing piece is the NULL session_id semantics and what happens for sessions the caller did start or that don't exist — a small but real gap for a diagnostic tool.

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 0% and there is only a single optional session_id parameter. The description partially compensates by implying session_id selects which session to inspect ('inspect a session you did not start'), but it never defines the parameter's format or what the default NULL value means (current session vs. most recent). This is a genuine gap given zero schema documentation.

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 specifies a clear verb and resource ('one-shot snapshot of a session') and enumerates exactly what the snapshot contains (status, tree, pending permissions/questions, last assistant text). It clearly distinguishes itself from polling/monitoring tools, and the full-caps 'DIAGNOSTIC ONLY' prefix makes its role unmistakable.

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?

This is exemplary. It explicitly forbids polling or monitoring, names the sibling tools (opencode_run / opencode_answer / opencode_permission) with the reason those are the correct choice (they block until turn ends), and specifies the only valid use cases: exceptional diagnostics after a timeout or inspecting a session you did not start. Nothing is left to inference.

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