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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds the output content (names, descriptions, modes), which is useful, but it does not disclose any additional behavioral traits such as scope limitations, pagination, or side effects beyond what annotations already cover.

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 a single, front-loaded sentence with no wasted words. It states the action, the resource, and the output fields efficiently.

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 simple list tool with a read-only, idempotent, non-destructive annotation profile and a fully documented optional parameter, the description fully explains what the tool returns. The schema covers the directory parameter, and annotations cover behavior, so 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% for the single 'directory' parameter, which is fully described in the schema. The tool description does not mention this parameter or add any meaning beyond the schema, so the baseline of 3 is appropriate.

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 uses a specific verb ('List') and resource ('agents'), and explicitly states the returned content (names, descriptions, modes). It clearly distinguishes from sibling list tools like opencode_command_list, opencode_tool_list, and opencode_provider_list by naming 'agents' as the target.

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 context is clear: this tool is for listing available agents. It does not explicitly mention when not to use it or name alternatives, but the purpose itself signals its appropriate use relative to other list tools. No exclusions or alternative routing are provided.

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

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

Annotations indicate destructiveHint=true, which is consistent with the description mentioning creating a new session, which could have side effects. However, the description doesn't add much beyond that, such as mentioning that it creates a session or that it might use resources. The openWorldHint is noted but not explained.

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 short and front-loaded with the key behavior, but it doesn't waste words. It clearly states the one-step nature and that it's the easiest way, which is concise and efficient. More detail could be added, but it's not overly lengthy.

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?

Given the tool's complexity with 9 parameters and an output schema, the description is sparse but not entirely incomplete. The schema and output schema cover most aspects. However, it doesn't mention the output response details or any side effects (e.g., session creation) that might be relevant for a one-step action. The description could benefit from mentioning that it is a higher-level convenience wrapper.

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?

The schema has 100% coverage, so the description of parameters is complete within the schema. The description does not add much beyond the schema, but the schema's own descriptions are detailed, including the format options and directory behavior. Given high coverage, a baseline of 3 is extended to 4 because the format parameter's description is notably clarifying about JSON Schema requirements.

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 states it asks OpenCode a question in one step, creating a session, sending the prompt, and returning the response. However, it doesn't clearly distinguish from similar tools like opencode_conversation or opencode_session_create, and the verb 'ask' is vague compared to more specific actions like 'send message' or 'get response'.

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 says this is the 'easiest way to interact', implying it's for quick, one-off interactions, but it doesn't explicitly state when to prefer this over opencode_message_send or opencode_session_create. No mention of when not to use it or what conditions might require a different tool.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a write operation. The description adds the useful context that credentials are stored globally and shared across all projects, which goes beyond the annotations. It does not disclose that existing credentials will be overwritten, but the destructiveHint partially covers that. Overall, the description adds moderate value without contradicting the annotations.

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 two sentences with no wasted words. The primary action is stated first, and the global-scope side effect is added efficiently. It is well-structured and front-loaded.

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?

Given the 100% schema coverage, output schema, and annotations covering destructive behavior, the description is largely sufficient. It explains the tool's purpose and a key side effect (global storage). It could mention that existing credentials for the provider may be overwritten, but the destructiveHint already signals this. No critical information needed to invoke the tool 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%—each parameter (key, type, providerId) has a description. The tool description adds no additional meaning beyond the schema, such as examples of valid provider IDs or auth types. Since the schema does the heavy lifting, the baseline of 3 is appropriate.

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 uses a specific verb ('Set') and resource ('authentication credentials for a provider') with a concrete example ('API key'). It is clear what the tool does, and the name opencode_auth_set reinforces this. However, it does not explicitly differentiate itself from sibling auth-related tools like opencode_provider_auth_methods or opencode_provider_oauth_authorize, so it lacks the sibling distinction that would merit a 5.

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 provides no guidance on when to use this tool versus alternatives. It does not mention that OAuth flows should use opencode_provider_oauth_authorize, nor does it state any exclusions or prerequisites. The only context given is that credentials are stored globally, which does not help an agent choose this tool over other auth-related operations.

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

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

With readOnlyHint and idempotentHint already present, the description adds meaningful behavior by explaining that it uses session summary metadata instead of fetching patches, and that detailed includes response text. This helps an agent predict cost and output behavior beyond the annotations.

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 two tight sentences. The core purpose is front-loaded, and the second sentence adds parameter guidance without redundancy or filler.

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 tool has five parameters, but the schema fully documents them and an output schema exists. The description explains the key usage distinction for jobId and detailed while leaving structural details to the schema. It is mostly complete, though the relationship between sessionId, jobId, and messageId could be summarized more explicitly.

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 enriches jobId by explaining it enables exact durable turn correlation, which goes beyond the schema's 'Durable job ID'. The detailed note largely repeats the schema, but the jobId guidance justifies moving above baseline.

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 uses a specific verb ('Get') and a concrete set of resources: current task status, pending input, todos, and file counts. It is clear about what the tool returns, though it does not explicitly distinguish itself from siblings like opencode_session_status or opencode_status.

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 clear context for when to use the tool: when you need task status, pending input, todos, and file counts without fetching patches. It also provides practical guidance on jobId for durable turn correlation and the detailed flag, but it does not explicitly name alternatives or say when not to use the tool.

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

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

Annotations already convey destructive and open-world behavior, and the description adds little beyond examples. It does not disclose that commands like /undo or /redo mutate session state, that effects may be significant, or what an agent should watch out for. There is no contradiction with annotations.

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?

A single front-loaded sentence with useful examples and no filler. Every word contributes to understanding what the tool does.

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 output schema and full parameter coverage reduce the burden on the description, but an agent is not told how to discover valid slash commands or how this relates to command_list and the TUI execution tools. Adequate but minimal.

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%, so the schema already documents all parameters. The description adds no parameter-level meaning beyond examples, but the baseline of 3 is appropriate because the schema carries the load.

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?

States a specific verb and resource: executing a slash command within a session, with concrete examples (/init, /undo, /redo). It is clear, though it does not explicitly distinguish itself from sibling tools like opencode_tui_execute_command or opencode_command_list.

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?

No guidance is given about when to use this tool versus alternatives such as opencode_command_list, opencode_shell_execute, or opencode_tui_execute_command. The context implies session-scoped slash commands, but there are no exclusions or selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds scope context ('built-in and custom slash commands') but no additional behavioral traits beyond what annotations provide.

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?

One sentence with no filler, front-loaded with the verb and object. The parenthetical adds necessary scope clarification without redundancy.

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?

This is a simple read-only listing operation with rich annotations, full schema coverage for its only parameter, and an output schema. 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?

The single optional parameter (directory) has 100% schema description coverage, so the schema fully documents it. The description adds no parameter-level information, but none is needed given 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 uses a specific verb ('List') and resource ('all available commands'), and the parenthetical clarifies that it covers both built-in and custom slash commands. This clearly distinguishes it from sibling tools like opencode_command_execute (execution) and opencode_tool_list (tools).

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 implies its use as a discovery step before executing commands, but it does not explicitly state when to use it vs alternatives or mention exclusions. The usage context is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds little behavioral context beyond a generic label. It does not say whether the returned value is the effective/resolved configuration, how the optional directory affects the result, or what happens when no project configuration exists.

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 one short, front-loaded sentence with no filler. Every word adds meaning, and the core operation is stated immediately.

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 simple getter with no required parameters, an output schema, and read-only annotations, the description is nearly sufficient. It does not, however, help an agent distinguish this from opencode_config_update or opencode_config_providers, and it relies on the schema to explain the directory behavior. The description alone is thin but not misleading.

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?

The input schema fully documents the only parameter, `directory`, including that it is an absolute path, that it targets a specific project when provided, and that omission uses the server's working directory. The tool description itself contributes no parameter detail, but the schema covers this dimension completely.

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 uses a clear verb and resource: 'Get the current opencode configuration.' It is easy to identify this as a read operation on the configuration. It does not explicitly call out sibling tools like opencode_config_update or opencode_config_providers, but the 'get' wording makes the primary purpose clear.

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 word 'current' implies this tool is for retrieving the active configuration rather than updating it or inspecting providers, so some usage context is present. However, it gives no explicit when-to-use or when-not-to-use guidance and does not mention alternatives among the sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no extra behavioral context (e.g., no mention of output format, but an output schema exists). It is consistent with the annotations, so no contradiction. Since annotations carry the burden, a 3 is appropriate.

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 a single, front-loaded sentence with no filler. It states the action and the key detail (default models) efficiently. Every word earns its place.

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 tool is simple, has an output schema that defines the return, and annotations cover safety. The description tells the agent what it does. The only gap is the lack of usage guidance relative to siblings, but for a straightforward list tool this is a minor omission. Overall, an agent can call it correctly with the provided information.

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?

The schema description covers 100% of the parameter (directory), so the schema already documents its meaning and optionality. The description adds nothing about parameters, so it does not exceed the baseline of 3 when schema coverage is high.

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 states a clear verb ('List') and resource ('configured providers') with an additional detail ('their default models'). It distinguishes from config_update (which is a write) and config_get (which gets config), though it does not explicitly contrast with opencode_provider_list, which could also list providers. The phrase 'configured' and 'default models' adds specificity.

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?

No guidance is given on when to use this tool versus alternatives like opencode_provider_list or opencode_provider_models. The agent must infer usage from the description alone, with no mention of conditions or exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the operation's mutating nature is known. However, the description adds no extra behavioral context—it does not explain what happens to existing configuration fields, whether the update merges or replaces, or any side effects beyond the annotation signals. This is minimal transparency.

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 concise, uses two short sentences, and clearly states the purpose at the start. There is no redundant fluff, and the partial config concept is front-loaded. It earns a 4 for efficiency, though it could have been more informative without much verbosity.

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?

Given the tool is destructive (per annotations) and has multiple siblings (opencode_config_get, opencode_config_providers), the description is incomplete. It lacks guidance on usage, potential risks, or what happens to the configuration. While an output schema exists, it does not compensate for the missing operational context. The agent needs more to call it safely and correctly.

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%, so both parameters (config and directory) are already documented in the schema. The description reinforces that config is a partial object, but this is already stated in the parameter description. No additional meaning is added beyond the schema, so a baseline 3 is appropriate.

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 states 'Update the opencode configuration' which clearly identifies the verb and resource. It mentions passing a partial config object, which indicates the update mechanism. However, it does not explicitly differentiate from sibling tools like opencode_config_get, so it's slightly below a 5.

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 provides no guidance on when to use this tool versus alternatives such as opencode_config_get for reading or opencode_config_providers. There is no mention of prerequisites, warnings, or exclusions. It leaves the agent to infer usage context.

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

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 well-covered. The description adds behavioral context by stating that it gathers multiple distinct pieces of context in a single call, which goes beyond the bare annotation data. Minor gap: it doesn't mention potential latency or external calls, but the annotations make this less critical.

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 two sentences with zero filler. The first sentence front-loads the tool's purpose and scope, listing concrete elements; the second gives a practical usage directive. Every word earns its place.

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 tool is simple: one optional parameter, no destructive actions, and a full output schema provided externally. The description tells the agent exactly what context is retrieved and when to use it. Combined with the annotations and schema, nothing an agent needs for correct invocation 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% — the only parameter, 'directory', is fully described in the input schema. The description adds no extra meaning about the parameter, but per the rubric baseline, a score of 3 is appropriate when the schema thoroughly documents parameters.

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 states a specific verb ('Get') and a well-defined resource ('full project context') with enumerated components (current project, path, VCS info, config, agents). It clearly differentiates from sibling tools by emphasizing 'one call' aggregation, which contrasts with granular tools like opencode_project_current or opencode_vcs_info.

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?

It explicitly gives a use context: 'Useful to understand the current state before starting work.' This implies the appropriate timing and intent. It does not explicitly compare to alternatives, but the notion of combining multiple lookups into one call inherently suggests a preferred approach for a consolidated overview.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that output is 'formatted for easy reading' and shows roles/content, which is useful. However, it does not disclose behavior like limit handling or pagination, and adds only modest context beyond annotations.

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 two sentences, direct and front-loaded with the primary action. It avoids redundancy and is appropriately sized for a simple read operation.

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 straightforward read-only tool with annotations covering safety, a complete output schema, and 100% parameter coverage, the description is sufficient. It clarifies the purpose and output format, and no critical details appear 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%, so all three parameters (limit, directory, sessionId) are already described in the schema. The tool description adds no additional meaning or clarification about these parameters, so it relies entirely on 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 the verb 'Get' and the resource 'full conversation history of a session', and specifies that it shows messages with roles and content. This distinguishes it from session metadata tools, though it doesn't explicitly name alternatives like opencode_message_list.

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?

No guidance is provided on when to use this tool versus sibling tools such as opencode_message_list or opencode_session_get. There are no explicit conditions, exclusions, or mentions of alternatives.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: connection failures return partial events, and stopping observation does not abort remote work. This helps an agent predict side effects and failure modes.

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 with no filler. The core verb and resource are front-loaded, and the scope choice appears immediately. Every sentence contributes behavioral or usage information.

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 covers the tool's purpose, scope variants, collection limits, failure behavior, and side-effect guarantees. With an output schema present and annotations covering safety, nothing essential is missing for an agent to invoke it correctly.

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%, so the schema already explains scope, directory, maxEvents, and durationMs. The description adds the relationship between maxEvents and duration, but this is marginal beyond the structured parameter 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 states a specific verb ('Poll'), a resource ('project events'), and an explicit scope option ('global scope'). It clearly distinguishes project-wide behavior from global behavior, so an agent understands exactly what the tool operates on.

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 makes the primary usage clear: poll project events, or explicitly select global scope. It does not name alternative sibling tools, but no sibling directly competes with event polling, and the scope selection is stated upfront.

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

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 adds no meaningful behavioral context beyond what 'List files and directories' implies, such as recursion, hidden files, or scope limits. It does not contradict the annotations.

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 a single sentence with no wasted words. It is appropriately concise for a simple tool whose parameter details and output structure are already provided elsewhere.

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 low-complexity list tool with strong annotations, full schema coverage, and an output schema, the description is nearly sufficient. The only gap is the lack of any sibling differentiation or usage context, which is accounted for in other dimensions rather than making the tool description incomplete for invocation.

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%, so the parameters are already fully documented in the input schema. The description adds no additional semantic detail about path interpretation, default behavior, or the directory/project parameter distinction.

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 uses a specific verb ('List') and resource ('files and directories at a path'), making the basic purpose clear. However, it does not differentiate this from similar file-related siblings like opencode_find_file or opencode_file_status, which could cause some ambiguity for an agent selecting among them.

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?

No guidance is given about when to use this tool versus alternatives such as opencode_find_file, opencode_file_read, or opencode_file_status. The only contextual hint is the path default, which appears in the schema; the description itself provides no usage direction or exclusions.

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

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 merely restates the read-only behavior without adding extra behavioral context such as encoding, binary file handling, or output size limits. It does not contradict the annotations.

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 a single succinct sentence with no filler or redundant content. It is front-loaded and immediately communicates the core operation. Every word earns its place.

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 simple read tool with a clear schema, full parameter coverage, an output schema, and comprehensive annotations, the description is sufficient for an agent to invoke it correctly. Additional context about file types or edge cases would be nice but is not necessary given the available structured metadata.

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?

The input schema covers 100% of the parameters with descriptions, so the schema does the heavy lifting. The tool description adds no additional parameter meaning beyond what the schema already provides. With full schema coverage, the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Read the content of a file.' This clearly distinguishes it from sibling tools like opencode_file_list or opencode_find_text. However, it does not explicitly differentiate itself from alternative file-related tools, though the name and wording make the intent obvious.

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?

No guidance is provided about when to use this tool versus file_list, find_text, or other file-related tools. There are no exclusions, prerequisites, or alternative suggestions. The intended usage is only implied by the tool name and description.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scope ('tracked files', 'VCS changes') but does not disclose operational details such as whether untracked files are excluded or what the output structure looks like; the output schema covers the latter. This mirrors the get_calls calibration where annotation coverage yields a baseline 3.

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 a single compact sentence that leads with the action and resource, and the parenthetical immediately disambiguates 'status' as VCS changes. No filler or redundant information.

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 simple, read-only, idempotent tool with one fully documented optional parameter and an output schema, the description is sufficient. Nothing an agent needs to select or invoke the tool 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 coverage is 100%; the single optional directory parameter is fully documented in the schema, including behavior when omitted. The description adds no parameter-specific meaning beyond that, so the baseline 3 applies.

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 uses a specific verb ('Get status') with a well-defined resource ('tracked files') and immediately clarifies the domain with 'VCS changes: modified, added, deleted, etc.' This is distinct from sibling file listing/reading tools and from the broader status tools, so an agent can tell what the tool is for.

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 clear context: use this when you need VCS change status for tracked files. It does not explicitly name alternatives or when-not-to-use conditions, but the scope is sufficiently unambiguous for this simple read-only operation.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the fuzzy-match behavior and clarifies the search-scope distinction between directory and searchDirectory. No contradictions with annotations.

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 a single sentence that is front-loaded with the essential purpose. It's appropriately minimal, though it could arguably mention the fuzzy-match behavior more explicitly as the key differentiator.

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?

Given the output schema exists, annotations cover safety, and all parameters are documented in the schema, the description is complete enough. It could add a note about how searchDirectory relates to directory, but the schema already covers this. Complexity is low; an agent can invoke this correctly.

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%, so the schema documents all parameters. The description adds the fuzzy-match semantics that apply to query. The directory parameter is already well-documented in the schema with its fallback behavior.

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 states a clear verb and resource: 'Find files and directories by name (fuzzy match)'. It distinguishes from siblings like opencode_find_text and opencode_find_symbol by focusing on file/directory names, though it doesn't explicitly name those alternatives.

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 implies when to use this tool: when searching for files/directories by name. It doesn't explicitly exclude alternatives like opencode_find_text or opencode_find_symbol, but the fuzzy-match-by-name phrasing is clear enough context for an agent to select it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds 'workspace' scope, implying it only searches within the current workspace, which is a useful behavioral constraint. However, it does not disclose return format, case sensitivity, or indexing behavior. Since annotations cover safety, a 3 is appropriate.

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?

A single, front-loaded sentence that is extremely concise and includes illustrative examples. No filler or redundant phrasing. The structure is optimal for a simple tool.

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 simple search tool with an output schema and safety annotations, the description is largely sufficient. It could mention whether the search is case-sensitive or requires an LSP server, but these are minor gaps. The presence of an output schema covers return values, and annotations cover side effects. Overall, it is complete enough for correct invocation.

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?

The input schema has 100% coverage, with clear descriptions for both 'query' (symbol name to search for) and 'directory' (absolute path). The tool description does not add any parameter-specific details beyond the schema, so it meets the baseline but adds no extra value.

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 the tool finds workspace symbols by name, with concrete examples (functions, classes, variables). It is unambiguous and distinguishes this from text/file search by focusing on 'symbols', even though it doesn't name alternatives. The verb 'find' and resource 'workspace symbols' are specific.

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?

No guidance is given on when to use this tool versus sibling search tools like opencode_find_text or opencode_find_file. The description does not mention scenarios, exclusions, or prerequisites (e.g., needing an initialized project). An agent must infer usage from the name alone.

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

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 adds that regex is supported and that results include file paths, line numbers, and matching lines, which is useful but does not disclose details like case sensitivity, default search scope, or behavior when no matches are found. No contradiction with annotations.

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?

One sentence with zero waste. The core action, scope, regex capability, and return values are all front-loaded and clearly stated.

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 read-only search tool with a full output schema and complete parameter documentation, the description is nearly complete. It could mention case sensitivity or default directory behavior, but the annotations and schema cover the essential safety and parameter context, so nothing critical 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%, so the schema already documents both parameters. The description adds the regex capability and the result shape, but it does not add meaning beyond the schema for the parameters themselves. Baseline 3 is appropriate.

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 states a specific verb ('Search'), a resource ('project files'), and the key capability ('regex supported'). It also names the return payload (file paths, line numbers, matching lines), which distinguishes it from sibling search tools like opencode_find_file and opencode_find_symbol.

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 implies usage for text/regex search across project files, and the sibling list shows opencode_find_file and opencode_find_symbol as alternatives, but the description does not explicitly say when to choose this tool over those siblings. It provides clear context but no exclusions or alternative routing.

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

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

The description informs that the task is durable, meaning it persists across failures, and that it returns immediately with IDs, indicating non-blocking behavior. This adds context beyond the annotations (readOnlyHint=false, destructiveHint=true) by explaining the operational semantics of background execution. It does not detail exactly how destructive it is, but the combination with annotations and the description is sufficient. The description doesn't contradict any annotations, as the destructive hint aligns with the fact that dispatching a task may have side effects.

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 concise sentences that state the core action, the immediate return, and the follow-up tools. No redundant or irrelevant information. The information is well-structured, with the main purpose first and usage guidance second. Perfectly sized for quick understanding.

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?

Given the tool's moderate complexity (9 params) and the presence of an output schema (describing the returned IDs), the description is nearly complete. It covers the purpose, key behavior, and next steps, which is crucial for an async tool. A minor gap is not mentioning any permission or auth requirements (e.g., for structured output), but the schema description already notes the StructuredOutput permission. So the description is adequate without repeating that. Thus, a 4 is justified as it covers the essential context for correct usage.

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?

The input schema already provides comprehensive descriptions for all 9 parameters (100% coverage). The description does not add extra param-specific detail, but the schema handles it. The description's focus on the tool's overall behavior, not individual parameters, is acceptable given the high schema coverage. No additional semantics needed beyond what's provided.

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?

Clearly states the tool dispatches a durable background task and immediately returns job, session, and message IDs. It uses a specific verb ('dispatch') with a defined resource (background task) and context ('durable'), distinguishing it from fire-and-forget or synchronous operations. The description is clear and unambiguous, separating it from sibling tools like opencode_run (synchronous) and opencode_message_send_async (no job handling).

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?

Explicitly states when to use this tool (to dispatch a background task) and directs users to alternatives: use opencode_check or opencode_wait to observe results, and job_cancel to stop the task. This gives clear guidance on the lifecycle and differentiates it from synchronous execution tools and other async tools like opencode_message_send_async. It also implies not to use this for synchronous interactions, guiding the agent to opencode_run or opencode_ask instead.

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

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 established. However, the description adds no behavioral context beyond the basic action—it does not explain what 'status' means (e.g., enabled/disabled, configured paths), whether it reads from configuration files, or what the response structure looks like. With annotations present, the description should still provide value, but it is essentially a restatement of the tool's name.

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 a single, front-loaded sentence with no redundant information. It is appropriately concise for a simple read-only status tool. While it could be richer, it avoids waste and communicates the core action efficiently.

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 tool is simple (one optional parameter, read-only, with an output schema). The description is minimal but technically sufficient for an agent to understand the basic operation. However, it omits details about what constitutes 'status', potential prerequisites (e.g., configured formatters), or how results are presented—information that would help an agent decide whether to call this tool. Since an output schema exists, return values need not be explained, but the description still feels sparse for a tool with a sibling named opencode_status.

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?

The schema covers 100% of the single optional parameter 'directory', including its meaning and default behavior. The description does not mention parameters at all, but because schema coverage is high, the baseline score is 3. No additional semantic value is added by the description.

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 the verb 'get' and the resource 'configured formatters', making the tool's purpose unambiguous. It is distinct from sibling tools like opencode_status or opencode_config_get because it targets formatters specifically, though it does not explicitly name alternatives or clarify what 'status' includes.

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 provides no guidance on when to use this tool versus alternatives such as opencode_status or opencode_config_get. There is no mention of scenarios that favor this tool, no exclusions, and no reference to related tools. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the 'health and version' scope but doesn't disclose what the response contains or whether the optional directory changes behavior beyond targeting. No contradiction with annotations.

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 a single short sentence that front-loads the core purpose. Every word earns its place; no filler or redundancy.

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 simple read-only health check with one optional parameter and an output schema, the description is mostly adequate. However, it doesn't clarify what 'health' includes (e.g., server status, version string) or when the directory parameter matters, which could leave an agent uncertain about expected results.

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%, so the schema already documents the directory parameter fully. The description adds no extra meaning about the parameter beyond what the schema provides. Baseline 3 is appropriate.

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 states a clear verb and resource: 'Check server health and version'. It is distinct from siblings like opencode_status or opencode_config_get, though it doesn't explicitly name a sibling to differentiate from. The purpose is unambiguous.

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 implies usage for checking server health/version but provides no explicit when-to-use guidance or alternatives. The optional directory parameter hints at targeting a specific project, but no context is given for when to use this vs other status-like tools (e.g., opencode_status, opencode_lsp_status).

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

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

Annotations already carry destructiveHint=true and readOnlyHint=false, and the description reinforces this with an explicit WARNING that the server terminates. It goes beyond the label by clarifying exactly what is destroyed: the current opencode instance/server. This is adequate transparency for a destructive shutdown 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?

Two short sentences front-load the operation and add a necessary warning. Every word earns its place; there is no filler or redundancy.

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 one-optional-parameter destructive tool with an output schema and clear safety annotations, the description covers the essential facts: function, target, and destructive consequence. The optional directory targeting behavior is fully covered by the schema, so no critical selection-time information 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%, so the directory parameter is fully documented in the schema. The description adds no parameter-specific semantics beyond the schema, matching the baseline for high schema coverage.

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 uses a specific verb, 'Dispose', names the resource ('current opencode instance'), and clarifies with 'shuts it down' and 'terminate the server'. This clearly distinguishes it from session-level tools like opencode_session_delete and from all read-only sibling tools.

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?

Usage is implied: call it to shut down the current opencode instance. However, it does not explicitly state when not to use it or name less destructive alternatives such as session deletion or abort. A sentence like 'Use only when the instance is no longer needed' would strengthen this.

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

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

Annotations already flag destructive/non-idempotent behavior; the description adds useful consequence detail by telling the agent that aborting the session also stops other work in that session. It does not contradict annotations.

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 short sentences, front-loaded with the primary action and a second sentence for the important side effect. No filler.

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 one-parameter destructive action with annotations and an output schema, the description covers what it does and the main side effect. It does not specify the job lifecycle outcome or async behavior, but those are minor given the schema and annotations.

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?

The schema provides no description for jobId and coverage is 0%, but the description ties the operation to 'a job,' so jobId is inferable as that job's ID. It still never explicitly says what jobId means or how to obtain it, so the description only partially compensates for the empty 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?

States a specific action—explicitly abort—and a target: the OpenCode session owned by a job. It clearly separates this job-scoped cancel/abort from direct session tools like opencode_session_abort, and the side-effect sentence reinforces the resource being acted on.

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?

Usage context is implied rather than spelled out: an agent can infer that this should be used when it needs to cancel a job and stop its session, but the description never names alternatives like opencode_session_abort or states when not to use it.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by specifying the response includes pending inputs and final results, which is beyond what annotations state. No contradictions found.

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 a single, front-loaded sentence with no wasted words. It conveys the action, the resource, and the key content of the response efficiently.

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?

Given the tool has one parameter, an output schema, and annotations covering safety, the description is complete. It tells the agent what the tool does and what to expect, with no missing prerequisites or side-effect information.

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?

With 0% schema description coverage, the description compensates by clarifying that the jobId parameter is the identifier of the job to observe. Though the name already implies this, the description reinforces it and ties the parameter to the action.

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 states a specific verb (observe) and resource (durable job) and explicitly includes what is returned (pending inputs and final results). It clearly distinguishes itself from siblings like job_cancel, job_list, and job_input, as it is the getter for a single job's details.

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 purpose is clear for a get operation, and the context is evident: use this when you need details of a specific job by ID. It does not explicitly list alternatives or exclusions, but the naming and description make the usage unambiguous relative to job_list and job_input.

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

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

Annotations only indicate destructiveHint true and readOnlyHint false, so the description carries the burden of behavioral disclosure. It adds key behaviors: 'Never approves automatically' clarifies that it does not auto-approve, and 'Omit responses to request MCP forms when supported, or receive manual response instructions' describes nuanced behavior. This provides meaningful context beyond the annotations without contradiction.

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 two sentences with no wasted words. The primary purpose is front-loaded, and the additional behavioral clauses are concise. Every sentence contributes essential information, making it highly efficient.

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?

Given the tool's moderate complexity (nested responses array, permission/question kinds) and the lack of parameter explanations, the description is incomplete. It does not explain how to structure responses or what the output schema returns. While an output schema exists, the description fails to clarify the request format, leaving an agent to guess at the meaning of fields like 'always' vs 'once' or 'reject'. The omission of parameter semantics makes this contextually insufficient for reliable invocation.

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 0%, so the description must compensate for explaining the parameters. However, it does not mention jobId or the responses structure, nor explain the enums (once/always/reject) or the answers array. The schema itself has no descriptions, so an agent would have to infer parameter usage from names and types. The description adds no parameter-specific meaning, severely undercompensating for the low schema coverage.

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 the tool's purpose: 'Respond to a job's pending questions or permissions.' This identifies the specific verb (respond) and resource (a job's questions/permissions). It adds a distinctive behavior (omitting responses to request MCP forms) that helps differentiate it from generic reply tools, though it does not explicitly name sibling tools like opencode_question_reply. It is specific enough to be understood, but lacks explicit sibling differentiation.

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 provides implicit usage context: use this tool when there are pending questions or permissions for a job, and it mentions a special case (omit responses to request MCP forms). However, it does not explicitly state when not to use it or name alternatives among the many sibling tools (e.g., opencode_question_reply for single questions). The guidance is present but not explicit about selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the 'locally retained' and 'credential scope' scoping constraints, but it does not disclose behaviors like default ordering, whether results are paginated, or what happens when limit is omitted.

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 a single, focused sentence that front-loads the verb and resource. It contains no filler or repetition, and every word contributes to scoping the operation.

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 tool is simple, has robust annotations, and an output schema exists, so return values do not need explanation. The core purpose is clear, but the undocumented `limit` parameter and the lack of explicit guidance about alternatives leave a moderate gap for an agent trying to invoke this tool correctly.

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 0%, and the description adds no meaning about the only parameter, `limit`. It does not mention the default behavior, the effect of omitting the parameter, or how limit interacts with the listed jobs, leaving the description to compensate for the schema gap without doing so.

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 uses a specific verb ('List') and resource ('locally retained jobs'), and clarifies the scope ('in this OpenCode server and credential scope'). It distinguishes this from job_get, job_cancel, and job_input by clearly positioning it as the enumeration operation.

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 clear context for when to use the tool: you list jobs retained locally in the server/credential scope. It does not explicitly name alternatives or state when not to use it, but the distinction from single-job operations is reasonably clear from the wording.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's 'write' adds no new behavioral insight beyond what is structured. It does not disclose side effects, persistence, error behavior, or rate limits. No additional value is provided over the annotations.

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 a single sentence with no filler words. It front-loads the core action and target, and every word earns its place. This is appropriately concise for a simple logging endpoint.

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?

Given the output schema exists and annotations cover the mutation/destructive nature, the description is minimally adequate: an agent can invoke the tool correctly by relying on the schema. However, it lacks any usage context or behavioral nuance beyond what structured fields provide, so it does not exceed the minimum viable completeness.

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%, meaning every parameter (service, level, message, extra, directory) is documented with its own description. The tool description does not reference any parameters, but the schema fully carries the semantic load, so the baseline of 3 applies.

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 states a specific verb ('write') and resource ('log entry to the opencode server'). It clearly identifies the tool's function and is distinct from all sibling tools, none of which are logging tools. The purpose is immediately understandable and not a tautology.

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 provides no guidance on when to use this tool, when not to use it, or any alternatives. There is no context about its intended role (e.g., diagnostics, auditing) or any prerequisites. An agent must infer usage from the tool name alone.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds no behavioral detail beyond restating that it returns status. It does not mention scope behavior, prerequisites, or any other context beyond what the structured metadata already provides.

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 a single short, front-loaded sentence with no filler. It states the core action, expands the acronym, and every word earns its place.

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 simple read-only status tool with a fully documented optional parameter, an output schema, and strong annotations, the description is sufficient to identify the tool's purpose. It lacks sibling-related usage guidance, but that gap is already captured in the usage dimension.

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%, so the single optional directory parameter is fully documented in the schema. The description itself says nothing about parameters, but because the schema carries the burden, the baseline score of 3 applies.

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 identifies a specific verb ('Get') and resource ('status of LSP servers'), and it expands the LSP acronym for clarity. It is distinguishable from sibling tools like opencode_mcp_status and opencode_formatter_status by the explicit LSP focus, though it does not explicitly contrast itself with them.

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?

No guidance is given on when to use this tool versus alternatives such as opencode_health, opencode_status, opencode_mcp_status, or opencode_formatter_status. The optional directory parameter is documented in the schema, but the description itself provides no usage context, exclusions, or decision criteria.

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

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

Annotations already declare destructiveHint=true and readOnly=false, so the description doesn't need to restate that. However, it adds little behavioral context beyond 'dynamically'—it doesn't mention whether it modifies configuration files, persists across restarts, or affects running sessions. It doesn't contradict annotations but adds minimal value beyond what annotations already imply.

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 a single concise sentence with no wasted words. It is front-loaded and efficient—there is no filler or redundancy.

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?

Given that this is a mutation tool with a nested config object and an output schema, the one-sentence description is insufficient. It doesn't explain the effect of the directory parameter, how the config object is used, or any side effects. The presence of many siblings also calls for more context to guide tool selection.

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 doesn't add any parameter-specific meaning; it just says 'Add an MCP server' without referencing the name, config, or directory parameters. It thus doesn't exceed the baseline provided by 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 a specific action (add) and resource (MCP server) with context ('dynamically to opencode'). It is distinct from siblings like config_update or mcp_status, though it doesn't explicitly differentiate. The verb and resource are clear and unambiguous.

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?

There is no guidance on when to use this tool versus alternatives like config_update or mcp_status. No context about prerequisites, typical scenarios, or exclusions. The description leaves usage entirely to the agent to infer.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context—such as permission requirements, rate limits, or how the directory parameter affects scope. It only restates the tool's purpose without disclosing any non-obvious behavior.

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 a single sentence that states the tool's function directly with no filler. It is front-loaded and easy to parse, containing exactly the information needed for purpose clarity.

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 simple read-only status tool with one optional parameter, an output schema, and clarifying annotations, the description is mostly sufficient. The schema explains the directory parameter, and the output schema documents return values. However, the description does not explicitly mention that the directory parameter changes the scope of the status check, which could be relevant for project-specific configurations.

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%, and the directory parameter is fully documented in the schema. The description adds no extra meaning or usage nuance beyond the schema, so the baseline score of 3 is appropriate.

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 'Get' and names the exact resource: 'status of all MCP servers configured in opencode'. This is unambiguous and distinguishes it from related tools like opencode_health (general health) or opencode_status (overall status) by targeting MCP servers specifically.

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 implies usage when MCP server status is needed, but it does not explicitly state when to choose this over alternatives like opencode_health or opencode_status, nor does it mention exclusions or prerequisites. There is minimal contextual guidance beyond what the name already conveys.

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

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 clear. The description adds no behavioral traits beyond 'Get details,' which is consistent with the annotations and adds minimal context. No contradiction exists.

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?

A single, concise sentence that front-loads the core purpose. No filler or redundant information. Every word earns its place.

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?

Given the simple read-only operation, the output schema, and the annotations, the description is complete for an agent to call the tool correctly. The required parameters are already listed in the schema, and the return format is defined by the output schema, so nothing essential 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 all three parameters (directory, messageId, sessionId) documented in the schema. The description does not add any additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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?

States a specific verb ('Get'), resource ('details of a specific message'), and scope ('in a session'). This clearly distinguishes it from siblings like opencode_message_list (listing messages) and opencode_message_send (sending messages). The purpose is unambiguous.

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 implies usage (retrieve details of one message) but provides no explicit guidance on when to choose this over opencode_message_list or how it differs from other session/message tools. No alternatives or exclusions are mentioned, leaving the agent to infer from the name.

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

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 adds that output is formatted with roles and content, which is useful but minimal; it does not disclose ordering, pagination behavior, or behavior when a sessionId is invalid.

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 a single, front-loaded sentence with no filler. It conveys the core operation, scope, and output shape efficiently.

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 straightforward read-only list operation, the combination of a clear description, 100% parameter coverage, a complete output schema, and strong annotations is nearly sufficient. The only minor gap is the lack of explicit guidance about ordering or pagination, but this is not critical for the tool's basic invocation.

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 all three parameters are already documented with descriptions. The tool description does not add extra parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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 the action ('List all messages'), the resource ('in a session'), and the output format ('showing roles and content'). It is easily distinguished from sibling tools like opencode_message_get because it explicitly targets the full message list rather than a single message.

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 implies the use case: a caller who needs all messages in a session. However, it does not explicitly name alternatives such as opencode_message_get for single-message retrieval or opencode_session_search for filtered queries, nor does it state any exclusions or prerequisites beyond the required sessionId.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds the key behavioral trait of waiting for the AI response, which is useful. It also mentions the format option requiring OpenCode permission for StructuredOutput tool, which is a behavioral constraint. However, it doesn't disclose what 'destructive' means in this context (e.g., does sending a message mutate session state irreversibly?), and it doesn't mention rate limits or side effects beyond the annotation hints. The description adds some value but not rich behavioral context.

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 two sentences with no waste. It front-loads the core action ('Send a prompt message to a session and wait for the AI response') and then adds the key parameter hints. It could be slightly more structured by explicitly naming the async sibling, but it is concise and readable.

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 tool has 10 parameters, an output schema, and annotations, so the description doesn't need to explain return values. However, given the complexity (10 params, multiple model-related fields, format options, noReply behavior), the description is thin. It doesn't explain when to use noReply, how format works, or how this differs from the async sibling. The output schema and annotations cover some gaps, but for a tool with this many options, more contextual guidance would help.

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%, so the schema already documents all 10 parameters. The description adds minimal parameter meaning beyond the schema: it mentions 'parts' (which maps to text) and 'optionally specify a model' (modelID). It doesn't explain the relationship between agent, modelID, providerID, and variant, which could be ambiguous. Baseline 3 is appropriate since the schema does the heavy lifting.

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 states a specific verb ('send'), a resource ('prompt message to a session'), and the key behavior ('wait for the AI response'). It also mentions using 'parts' to send text and optionally specifying a model. However, it doesn't explicitly distinguish itself from the sibling opencode_message_send_async, which is a close alternative, so it loses a point on sibling differentiation.

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 implies usage: send a prompt and wait for the response. It mentions 'optionally specify a model' and 'use parts to send text', giving some context. However, it does not explicitly state when to use this tool versus opencode_message_send_async (the async sibling), nor does it mention when to use noReply or other alternatives. The guidance is implied rather than explicit.

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

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

Annotations already flag mutating behavior (destructiveHint=true, readOnlyHint=false), so the description adds value by disclosing the async timing behavior and the exact mechanism for correlating the result to a turn via opencode_wait. This goes beyond what annotations alone convey, though it doesn't cover failure modes or side effects in depth.

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, no filler, front-loaded with the core action and outcome. The follow-up instruction earns its place by explaining the purpose of the returned messageId in a concrete workflow.

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 an output schema and well-documented parameters, the description covers the critical async workflow and links to the necessary companion tool. It is slightly light on what asynchronous dispatch means for error handling or response timing, but nothing essential to invoking 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 coverage is 100% and every parameter already has a description. The tool description adds limited semantic value, mostly by explaining the role of sessionId in the follow-up wait step, but it does not deepen understanding of parameters like format, agent, or providerID 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?

Description states a specific action ('Send a prompt asynchronously') and a specific result ('return its messageId'). It is clearly distinguishable from the sibling opencode_message_send by the explicit async qualifier, and from opencode_wait by describing the send-vs-observe relationship.

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?

Provides clear contextual guidance: after sending, pass sessionId and messageId to opencode_wait to observe the exact turn. It does not explicitly call out when not to use it or name the synchronous alternative, but the workflow is unambiguous enough for an agent to know how to use it.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which cover the safety profile. The description adds no extra behavioral context beyond the operation, such as how the optional directory parameter affects the result or what the return value contains, but it does not contradict the annotations.

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 a single, front-loaded sentence with no filler or redundant wording. It is appropriately sized for a trivial getter tool.

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?

Given the fully documented schema, the detailed annotations, and the presence of an output schema, the one-line description is nearly sufficient for an agent to invoke the tool correctly. It lacks only an explicit pointer to related project/status tools, which is a minor gap rather than a critical omission.

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%, and the single optional 'directory' parameter is already documented in the schema, including the fallback behavior when omitted. The description itself adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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 names a concrete operation ('get') and a specific resource ('current working path of the opencode server'), so an agent can clearly tell what the tool does. It does not explicitly contrast it with sibling tools like opencode_project_current or opencode_status, but the path resource is distinct enough to avoid serious confusion.

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?

No guidance is given about when to use this tool rather than related getters such as opencode_project_current or opencode_status. The description simply states what the tool does, leaving the agent to infer selection criteria without explicit help.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: it lists what kinds of requests appear (shell commands, file access) and instructs the agent to respond via a specific sibling tool. This goes beyond the annotations without contradicting them.

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 with no waste. The core purpose is front-loaded, and the follow-up instruction is placed immediately after. Efficient and well-structured.

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?

With an output schema present, return values are covered. The description explains the tool's scope, the trigger conditions, and the recommended follow-up action. For a simple listing tool, nothing essential 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%, so the `directory` parameter is already fully documented. The tool description does not add additional semantics about the parameter, so the baseline of 3 is appropriate.

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 states a specific verb ('List') and resource ('all pending permission requests across all sessions'), and distinguishes itself from the sibling `opencode_session_permission` by noting the global scope and providing concrete examples of what triggers a pending request (shell command, file access). This is clear and unambiguous.

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?

It explains when to use the tool: when a session is blocked waiting for approval, and provides the immediate next step by instructing to respond with `opencode_session_permission`. It doesn't explicitly exclude alternatives, but the context makes it obvious this is the tool for enumerating pending requests.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds no behavioral context such as what 'active' means, whether a directory changes the target, or what happens when no active project exists. No contradiction with annotations.

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 a single efficient sentence with the main action front-loaded. It wastes no words, though it could afford one clarifying sentence about the active-project concept or sibling distinction.

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 simple read-only getter with an output schema and no required parameters, the description is minimally viable. However, it leaves 'active project' undefined and does not explain how the directory parameter relates, so an agent may still need to infer context.

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%, and the single directory parameter is well described there. The tool description adds no additional meaning, so the baseline of 3 is appropriate.

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 states a clear verb and resource: 'Get the current active project.' It distinguishes the tool from list/init siblings by pointing at a single active project, but it does not explicitly contrast any sibling.

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?

There is no guidance about when to use this tool instead of opencode_project_list or opencode_project_init, nor about what makes a project 'active.' The optional directory parameter is documented only in the schema, not in terms of usage strategy.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, covering the safety profile. The description adds useful context about operating on the local filesystem and supporting parallel workloads. However, it never explains what 'initialize' or 'open' actually changes on disk, leaving the destructive side effect underspecified.

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 earning its place: the first states the core action, the second gives concrete use cases, and the third establishes the filesystem boundary. There is no filler, repetition, or schema duplication, and the purpose is front-loaded.

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 single-parameter tool with annotations and an output schema, the description covers the essential operational context: what it acts on, where, and when to use it. The main omission is the precise nature of the destructive hint, but that is a minor gap given the annotations and simplicity of the 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 description coverage is 100%, with the path parameter already documented in the schema. The description adds no new parameter-level details; it restates the idea of a directory path and adds local vs. remote scope. Baseline 3 is appropriate because the schema fully covers parameter semantics.

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 names a specific verb and resource: initialize or open a project directory to host an OpenCode session. It clearly distinguishes itself from read-only project tools and session tools by focusing on directory creation/opening for parallel workloads. The local/remote boundary further separates it from other tools.

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 explicitly states when to use the tool: to create new empty folders or to open preexisting projects for parallel code generation workloads. It also gives a clear exclusion by saying remote server directories must be created separately. It does not name a specific alternative tool, but the usage conditions are sufficient for an agent to select it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the 'all projects' scope and the directory targeting behavior, but does not disclose details like whether the list is sorted, whether it includes hidden projects, or what happens when directory is invalid. With strong annotations, a 3 is appropriate.

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?

A single sentence that states the action and scope with zero waste. The description is front-loaded and every word earns its place.

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 simple read-only list tool with an output schema, full annotations, and one optional parameter, the description is nearly complete. The only minor gap is not explaining what the output contains (e.g., project names, paths), but the output schema likely covers that, and the description's job is not to repeat structured data.

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%, so the schema already documents the directory parameter. The description adds the context that omitting directory uses the server's working directory, which is already in the schema. No additional semantic value beyond the schema is provided, so baseline 3 applies.

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 uses a specific verb ('List') and resource ('all projects known to the opencode server'), which clearly distinguishes it from project_init and project_current. It does not explicitly name sibling alternatives, but the scope is unambiguous.

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 implies a simple read-only listing use case, and the optional directory parameter provides context for targeting a project. However, it does not explicitly state when to use this tool versus project_current or project_init, nor does it mention any exclusions.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the bulk-scope behavior — it returns auth methods for ALL providers rather than a single provider — which is useful context beyond the annotations. It does not disclose details like whether an active server connection is required, but with output schema present and safety fully covered by annotations, a 3 is appropriate.

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?

A single 8-word sentence that front-loads the verb and resource with zero filler. Every word contributes meaning, and no redundant restatement of the tool name appears.

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 simple read-only listing tool, the combination of annotations (safety profile), a complete input schema (100% param coverage), and an output schema makes the description nearly sufficient. The main gap is the lack of differentiation from auth-related siblings, which belongs to usage guidance rather than this dimension. Nothing an agent needs to invoke the tool 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%, so the directory parameter is already fully documented in the input schema. The description adds no parameter-level detail, and its 'all providers' claim only loosely implies that the directory parameter does not scope the results to a single provider. Baseline 3 is correct since the schema carries the semantic weight.

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 states a specific verb (get) and resource (available authentication methods for all providers), which distinguishes it from siblings like opencode_provider_list (providers), opencode_provider_models (models), and opencode_auth_set (setting auth). The scope qualifier 'for all providers' helps differentiate it from per-provider auth actions like opencode_provider_oauth_authorize, though siblings are not named explicitly.

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?

No explicit guidance is given about when to use this tool versus related siblings such as opencode_provider_oauth_authorize, opencode_provider_oauth_callback, or opencode_auth_set. The phrase 'for all providers' implies scope but does not tell the agent when to choose this over alternatives or whether it is a prerequisite before authorizing a provider.

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

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

Annotations already cover the safety profile with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat those. It adds useful context by stating the output is a 'compact summary' with connection status, but does not detail response fields or directory-dependent behavior; the output schema likely covers the rest.

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 with no filler. The primary action is front-loaded, and the alternative tool is mentioned efficiently in the second sentence. Every word earns its place.

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 read-only list operation with full schema coverage, clear annotations, and an output schema, the description provides everything needed to call it correctly. It even routes the agent to the relevant sibling for model details.

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?

The only parameter, directory, has 100% schema description coverage with a clear explanation. The tool description adds no parameter-level semantics, which is acceptable because the schema already fully documents the optional parameter.

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 uses a specific verb and resource: 'List all configured providers with their connection status.' It clearly states what the tool does and differentiates it from opencode_provider_models, which is explicitly mentioned as the tool for viewing models.

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 a clear routing cue by saying 'use opencode_provider_models to see models for a specific provider,' which helps distinguish the tool from its most relevant sibling. It does not enumerate other provider-related siblings like auth methods or testing, but the core use case is clear.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the useful prerequisite dependency on opencode_provider_list, but does not disclose other behavioral details such as default limits or pagination, which are handled by the schema and output 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?

Two concise sentences with no redundancy. The core purpose is front-loaded, and the prerequisite instruction is provided immediately after, making the description efficient and scannable.

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 simple read-only list operation, the description is complete: it states what the tool does, names the required dependency, and the schema plus output schema cover parameters and return structure. Nothing an agent needs to invoke 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%, so all three parameters are already documented with clear descriptions. The tool description does not add further meaning beyond implying providerId is central, which the schema already states.

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?

Description states a specific verb ('List'), resource ('available models'), and scope ('for a specific provider'). It also names the prerequisite sibling (opencode_provider_list), making it easy to distinguish from other provider-related tools.

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 clear usage context by instructing the agent to call opencode_provider_list first to obtain provider IDs. It does not explicitly mention alternatives or when not to use this tool, but the prerequisite guidance is actionable and contextually sufficient.

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

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

Annotations already indicate a non-read-only, non-idempotent, open-world, destructive operation, so the description need not repeat those flags. However, it adds no behavioral context beyond the tool name, such as whether this launches an external browser flow, requires user interaction, or expects a subsequent callback. It does not contradict the annotations, but it also does not enrich them.

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 a single, front-loaded sentence with no filler or repetition. It is efficient, but it may be too sparse for a tool with three parameters and nested object inputs; conciseness is achieved by omitting useful operational detail rather than by condensing rich content.

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 tool has moderate complexity and participates in a multi-step OAuth flow, yet the description does not mention the surrounding sequence: resolving provider IDs, selecting an auth method, or completing authorization via opencode_provider_oauth_callback. Although the schema is well-described and an output schema exists, the description alone leaves the agent without enough process context to use the tool confidently.

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 providerId, method, and inputs already documented meaningfully, including the method's default and its link to opencode_provider_auth_methods. The tool description itself contributes no additional parameter semantics. This stays at the baseline for full schema coverage.

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 states a specific action ('Start') and resource ('OAuth authorization for a provider'), making it clear that this tool initiates rather than completes an OAuth flow. It does not explicitly contrast with sibling opencode_provider_oauth_callback, but the verb 'start' differentiates initiation from callback handling. Some ambiguity remains about what 'starting authorization' concretely entails.

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 no guidance on when to use this tool versus alternatives such as opencode_provider_auth_methods or opencode_provider_oauth_callback. It does not mention prerequisites like resolving provider IDs or auth method indices before authorizing. The only sequencing hints are implicit in the schema, not in the description.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description adds no behavioral context beyond these flags. It does not disclose that completing the callback may store credentials, modify provider state, or require a prior authorization step. With annotations present, the description should at least add sequencing or side-effect details, which it does not.

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 a single concise sentence with no fluff, which is structurally efficient. However, it is under-specified – it lacks any contextual or clarifying information that would make the sentence 'earn its place'. It is not verbose, but it is also not informative enough to be considered well-structured.

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 an OAuth callback tool with nested objects, an output schema, and annotations, the description is far too minimal. It does not explain the prerequisite of having called the authorize tool, the expected redirect flow, or what happens after the callback is processed. An agent lacks the context needed to correctly sequence this tool in a workflow.

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% – both providerId and callbackData are already described in the schema. The description adds no additional meaning or usage hints for these parameters, so the baseline of 3 applies. The callbackData object's 'method' and 'code' fields are already self-explanatory from 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 states a clear verb and resource ('Handle OAuth callback for a provider'), which conveys the basic function. However, it does not distinguish this from the sibling 'opencode_provider_oauth_authorize' – an agent cannot tell that this is the second step of the OAuth flow (after user redirect) versus the initial authorization request. It is clear but lacks differentiation.

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 provides no guidance on when to invoke this tool or how it fits into the OAuth flow. There is no mention that it should be called after the user has been redirected back from the provider, nor any exclusions or alternatives. An agent has to infer the usage context from the name alone.

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

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

The annotations already indicate destructiveHint=true and idempotentHint=false, which signal that this tool creates and cleans up a temporary session. The description adds context about the temporary nature and side effects (creates a session, cleans up). However, it doesn't disclose potential side effects like cost (if the provider is paid) or that it might leave artifacts if cleanup fails. Given the annotations carry the destructive hint, the description adds moderate value but doesn't fully elaborate on edge cases.

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 two sentences and front-loads the core action. Every sentence is informative: the first states the purpose and process, the second gives a contextual use case. No filler or redundancy. It's appropriately concise.

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 is sufficient for an agent to understand what the tool does and when to use it. It covers the primary use case (debugging auth) and hints at the process. With the output schema present and annotations covering destructive behavior, the description doesn't need to explain return values or side effects in detail. Slight gap: no mention of time requirements or failure handling, but given the tool is a quick test, this is acceptable.

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 documents all five parameters with descriptions. The description adds no extra parameter-level detail beyond what's in the schema. For example, 'format' and 'modelID' are already explained. The description mentions 'providerId' implicitly but doesn't add usage nuances. Given full schema coverage, the baseline is 3, and the description doesn't elevate it.

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 the purpose: 'Quick-test whether a provider is working.' It specifies the exact process (creates a temporary session, sends a trivial prompt, checks the response, cleans up) and the target resource (provider). It is distinct from sibling tools like opencode_provider_list (listing) or opencode_provider_models (model discovery), as it focuses on testing connectivity and auth.

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 explicitly states when to use: 'Great for debugging auth issues.' It implies that for other provider-related tasks (e.g., listing models, configuring), one would use other tools. However, it does not explicitly mention alternatives or when NOT to use it (e.g., not for performance testing), but the purpose is clear enough for an agent to infer.

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

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 description does not need to repeat these. It adds the concept of 'pending' and 'optionally filtered to a session', which gives useful behavioral context beyond the annotations. However, it does not describe return format or edge cases, which are partially covered by the output 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?

The description is a single, efficient sentence that front-loads the main purpose ('List pending OpenCode questions') and then adds the optional filter. Every word earns its place with no redundancy.

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 simple list operation with an output schema and annotations covering safety, the description is complete enough. It states the core action, the optional filter, and the subject (pending questions). It does not elaborate on question semantics, but sibling tools like opencode_question_reply provide context. The main missing piece is explicit guidance on when to use this versus alternatives, which is partially addressed in usage_guidelines.

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 50% (directory has a description, sessionId does not). The description mentions 'optionally filtered to a session', which gives meaning to sessionId as the filter, partially compensating for the missing schema description. Directory is already described in the schema, so the description adds value for sessionId but does not fully explain its format or constraints.

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 uses a specific verb 'List' and a clear resource 'pending OpenCode questions', with an optional filter by session. This clearly distinguishes it from sibling tools like opencode_session_list (lists sessions) and opencode_message_list (lists messages), which have different purposes.

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 states the primary action and the optional filter but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or conditions. The context of sibling tools (e.g., opencode_question_reply) implies usage, but it is not made explicit.

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

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

Annotations already mark this as destructive, non-read-only, and non-idempotent, so the description does not need to restate that. It adds the 'pending' scope and 'explicitly' nuance, but does not describe side effects or irreversibility beyond what the annotations imply.

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?

A single, front-loaded sentence with no filler. Every word adds meaning: 'Reject', 'pending', and 'explicitly' all contribute to understanding the action.

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 tool is simple and has an output schema plus annotations covering destructiveness, but the description still leaves the agent to infer the role of requestId and when rejection is appropriate. Adequate for a minimal call, but with clear gaps.

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?

The description does not explain that requestId identifies the question to reject, and the schema only gives it a minLength with no semantic description. Directory is described in the schema, but at 50% coverage the description should compensate for requestId and does not.

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 uses a specific verb ('Reject') and a clear resource ('a pending OpenCode question'), which makes the tool's function immediately understandable and distinguishes it from siblings like opencode_question_reply and opencode_question_list.

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?

No guidance is given about when to reject a question versus replying to it, or what conditions must hold (e.g., the question must still be pending). The word 'pending' hints at the precondition, but no alternatives or exclusions are mentioned.

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

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

Annotations declare destructiveHint: true and openWorldHint: true, so the agent already knows this mutates state. The description adds minimal behavioral context—'Answer' implies a one-way submission, and 'per question' hints at cardinality, but it doesn't disclose side effects beyond that. It adds no new behavioral traits that annotations don't cover, so a 3 is appropriate.

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 concise, two sentences, with the core purpose front-loaded. No unnecessary words. It could possibly add a hint about multiple questions in one call, but as is, it's efficient and well-structured. Loses a point for not explicitly hinting at the array-of-arrays shape in the first sentence, but the structure is solid.

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?

Because an output schema exists (per context signals), return handling is covered elsewhere. The description covers the essential input format but omits prerequisites, such as the requirement that a question request must be currently active or that this action is final and cannot be retracted. For a destructive tool with a nested answers structure, more context would help an agent use it correctly, so a 3 is fair.

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 only 33% (only directory is described). The description's phrase 'Supply one array of selected labels or free text per question' clarifies the answers parameter structure (array of arrays of strings) and its alignment with questions. However, it doesn't explain requestId beyond what the schema implies (a required string), and directory already has its own schema description. It partially compensates for the low coverage but leaves requestId semantics unexplained.

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 the tool's purpose: 'Answer an OpenCode question request.' This specifies a verb (answer) and a resource (question request), distinguishing it from sibling opencode_question_reject. It is clear and specific, though it doesn't explicitly differentiate from other reply/send tools, so not a perfect 5.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention that it should only be used for pending questions, nor does it point to opencode_question_reject for the reject case. Sibling tools exist but are not referenced. Usage context is only implied by the resource name.

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