Ask opencode (new session)

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

Annotations state readOnlyHint=false, openWorldHint=true, and idempotentHint=false, and the description substantially supplements these by explaining auth requirements, the slowness of free queue-scheduled models, timeout_s rationale, and sandbox enforcement being agent-enforced rather than an OS boundary. It also warns against 'danger-full-access' and clarifies that a refused tool call is blocked by opencode, not the kernel.

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 longer than average but remains dense and well-organized, front-loading the core purpose before covering credentials, output format, workspace usage, and performance warnings. Every sentence carries operational value; the only reason not to give 5 is that some caveats, such as the slowness warning, are also reflected in the sandbox and timeout parameter descriptions.

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 open-world capabilities, auth options, sandbox policies, and performance caveats, the description covers the critical ground: no-subscription backend, paid model alternatives, final-message return value, workspace context, timeout behavior, and sandbox limitations. An output schema exists, so detailed return shape doesn't need to be restated. There is no major operational gap.

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. The description adds useful extra meaning beyond the schema: workspace is recommended for context-aware answers, timeout_s defaults to 300 because free models are slow, and model selection guidance encourages a paid model for long tasks. These additions genuinely help an agent choose parameter values.

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: 'Ask opencode (`opencode run`) a question or task in a NEW session.' It clearly distinguishes itself from continuation tools by explicitly stating 'NEW session' and describes what the tool returns (the agent's final message reconstructed from event data).

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 gives concrete usage context: the free opencode models require zero credentials, a project directory can be pointed to for context-aware answers, and configured paid models are preferred for long tasks. It also mentions 'For a hard boundary, use codex' as an alternative. However, it does not explicitly name or contrast sibling ask tools like codex_ask, copilot_ask, or antigravity_ask.

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