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

With no annotations provided, the description carries more burden. It communicates the read-only nature through 'List' and specifies the return fields, but it does not disclose permissions, pagination, sorting, or any other operational behavior beyond the basic listing action.

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. Every part of it ('List all available agents', return fields) earns its place for a simple list 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 simple, optional-param list tool with a fully documented schema and no output schema, the description is nearly complete. It states the resource and return fields, though it could optionally note that the listing is read-only or scoped by the optional directory.

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% description coverage for the single optional directory parameter, so the schema already explains its meaning and default. The description adds no further parameter semantics, making the baseline 3 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 (available agents), and it names the returned fields (names, descriptions, modes). It clearly distinguishes this tool from the many session, message, file, and provider listing siblings by specifying agents as the resource.

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 by the purpose: an agent would call this when it needs to discover available agents. However, the description offers no explicit when-to-use guidance, no exclusions, and no alternatives or prerequisites.

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 no annotations, the description carries the full burden; it does usefully disclose that a session is created as a side effect and that the call returns the AI response synchronously (implying it blocks). It says nothing about session persistence, timeouts, or auth requirements.

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 tight sentence with the core action front-loaded and zero filler; the colon-separated step list efficiently conveys the composite flow.

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 9-parameter tool with 11% schema coverage, no annotations, and no output schema, one sentence is not enough. Neither the parameter semantics nor the behavioral profile (what session is created, whether it persists, blocking/timeout behavior) is covered.

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?

Nine parameters with only 11% schema description coverage (just 'directory'), and the description adds no meaning for agent, format, system, modelID, variant, providerID, or title. It does not compensate for the schema gap despite that being the description's job here.

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 ('Ask') and resource ('OpenCode') and enumerates the internal steps (create a session, send a prompt, return the AI response), which distinguishes it as a one-shot wrapper rather than the raw session/message primitives. It does not explicitly name the sibling tools it replaces, so sibling differentiation is only implied.

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 phrase 'in one step' hints at convenience versus multi-step alternatives but never states when to choose this over opencode_session_create + opencode_message_send, nor any prerequisites or exclusions. An agent still has to guess whether this is preferred or merely a shortcut.

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?

No annotations are supplied, so the description carries the full behavioral burden. For a credential-mutating tool it omits whether existing credentials are overwritten, where secrets are stored, whether a restart or re-auth is required, and whether the operation is reversible.

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 tight sentence with no filler and the action front-loaded. It is appropriately sized, though the brevity is partly the cause of the gaps 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?

With no annotations, no output schema, and 0% parameter documentation, the description is the only source of behavioral detail and it supplies almost none. An agent could invoke it but would be guessing on 'type' semantics and side effects.

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% for all three required parameters. The description hints only at 'key' (API key) and implicitly at provider; the 'type' parameter is completely undefined, leaving the agent no basis for choosing a valid 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 states a specific verb (Set) and resource (authentication credentials for a provider) and the '(API key)' qualifier implicitly separates it from OAuth-based siblings like opencode_provider_oauth_authorize. It stops short of explicitly naming those alternatives, so it does not fully earn 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?

There is no guidance on when to use this tool versus opencode_provider_oauth_authorize/opencode_provider_oauth_callback or opencode_provider_auth_methods, which the agent must consult first to know which auth type a provider supports. No prerequisites, no mention that the provider must already exist.

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?

No annotations are provided, so the description carries the full burden. It does not say whether this blocks, polls, or snapshots, what 'observing a session' entails, whether it requires an active session, or what errors occur for a missing session — a significant gap for a status/observation tool with zero annotation coverage.

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, front-loaded sentences with no filler. Efficient, though the brevity comes at the cost of substance rather than from tight editing of 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?

With no annotations, no output schema, 3 parameters at 33% coverage, and a large sibling set containing near-duplicate status tools, the description is far too thin to let an agent call it correctly or prefer it over alternatives.

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 only 33% (only 'directory' is documented). The description partially clarifies 'detailed' ('for full response text'), but leaves 'sessionId' and the directory default semantics to the schema. It adds marginal value and does not compensate for the low 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?

States a verb and resource ('Get current task status by observing a session'), which is more than a tautology. However, it does not distinguish itself from near-identical siblings like opencode_session_status or opencode_session_get, leaving the agent unsure which status tool to pick.

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 versus opencode_session_status, opencode_job_get, or opencode_wait, all of which plausibly cover the same 'task status' territory. The only hint ('Pass detailed for full response text') is a parameter note, not usage guidance.

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?

No annotations are provided, so the description carries the full behavioral burden. It says only that a command is executed; it does not disclose whether commands like /init or /undo mutate session state, what permissions are required, whether effects are reversible, or what the tool returns. The examples hint at action but not at consequences.

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 single sentence is front-loaded with the verb and resource, contains no filler, and the examples are useful. It is efficient, though its extreme brevity leaves substantive gaps that belong to other dimensions.

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 8-parameter action tool with no annotations and no output schema, the description is largely incomplete. It establishes purpose but omits parameter meaning, behavioral effects, prerequisites, and how to choose this over adjacent session, shell, or command-list tools.

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 13%, so the description must compensate for six undocumented parameters (agent, modelID, variant, arguments, providerID, and command itself). It only implicitly covers sessionId and command ('in a session') with no syntax, format, or role for the remaining arguments.

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 gives a specific verb ('Execute') and resource ('a slash command in a session'), with examples (/init, /undo) that clarify the kind of command. It does not explicitly distinguish itself from close siblings such as opencode_command_list or opencode_tui_execute_command, but the session-scoped slash-command framing is clear enough.

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 opencode_command_list (to discover commands), opencode_shell_execute, or opencode_tui_execute_command. The examples imply a class of commands but provide no conditions, prerequisites, 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?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether this is a safe read (though the name implies it), what scope "all" covers (global vs project-defined commands), or the response shape. For an unannotated tool this is a notable gap.

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 short sentence, appropriately sized and front-loaded. It is efficient, though the word "all" is unqualified and slightly ambiguous rather than maximally informative.

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 low complexity (one optional param, no output schema, no annotations), the description is minimally adequate but leaves ambiguity about scope of commands and their format. Complete enough to call, not complete enough to predict the result.

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 adds nothing about parameter behavior or defaults beyond what the schema already provides, making 3 the correct 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?

States a specific verb+resource ("List all available slash commands"), which is clear and distinguishable from the execution sibling opencode_command_execute. It does not explicitly name any sibling or contrast itself, so it stops short of 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?

There is no when-to-use guidance at all: nothing says to call this before opencode_command_execute to discover valid command names, nor when-not to call it. Usage is only weakly implied by 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?

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read-only, non-destructive operation, but the description says nothing about permissions, whether it returns merged/effective config versus raw files, or what a caller should expect. It adds essentially no behavioral context beyond the verb.

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 front-loaded sentence with no wasted words, well matched to a trivial single-parameter getter. It is efficient rather than padded, though it is thin enough that no extra structure was needed.

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 no output schema and no annotations, the description is minimally adequate: it names the resource and scope ('current'). It omits what the returned configuration contains or how it is scoped, which an agent might need to interpret results 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?

The single parameter has 100% schema description coverage, including the 'defaults to the server default project' note, so the baseline of 3 applies. The description adds no format or scope detail about the directory parameter beyond what the schema already documents.

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+resource combination ('Get the current opencode configuration'), so the agent knows this reads configuration state. However, it does not differentiate from the adjacent opencode_config_update or opencode_config_providers siblings, so the agent must infer the boundary from the names alone.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as opencode_config_update or opencode_config_providers. Only the faintest implied usage ('current' suggests reading live state) is present.

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?

No annotations are provided, so the description carries the full behavioral burden. The verb 'List' implies a read-only, non-destructive operation, but the description says nothing about permissions, whether output can be large, or formatting; for a tool with zero annotation coverage this is thin.

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 zero filler; the resource and the returned content (default models) come first.

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 one-parameter read tool with no output schema, minimal description is acceptable. However, it omits how this differs from the closely related provider_list/provider_models tools, which is the main thing an agent needs to disambiguate.

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?

There is one optional parameter with 100% schema description coverage, so the schema already explains 'directory' and its default. The description adds nothing about the parameter or how the directory scopes results, 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 states a specific verb and resource: list configured providers plus their default models. That is clearer than a bare name restatement, but it does not distinguish itself from near-identical siblings such as opencode_provider_list and opencode_provider_models, so an agent cannot tell which of the three to pick.

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 when-to-use, when-not, or prerequisite guidance is given. There is no mention of how this differs from opencode_provider_list or opencode_config_get, leaving the agent to guess based on names.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Partial config object' hints at merge semantics, which is a genuinely valuable signal, but nothing is said about persistence (disk vs in-memory), whether a restart/take-effect is required, permissions, reversibility, or how nested fields are treated on merge — all critical for a mutation tool targeting a nested config.

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 action, and no filler. It is efficient, though its brevity for a nested-object mutation tool edges toward under-specification rather than deliberate conciseness.

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 mutation tool with no annotations, no output schema, and a nested-object parameter, the description should explain merge-vs-replace behavior and whether changes persist. With only 'pass a partial config object', the agent lacks enough to call it confidently and predict the effect.

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 both parameters and their meanings are already documented in the schema. The description's phrase 'partial config object' restates the schema's 'Partial config object with fields to update' without adding format or merging depth details, 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?

States a specific verb and resource ('Update the opencode configuration') that an agent can read at face value. It does not name or distinguish itself from the sibling opencode_config_get, so differentiation is left to the agent, but the purpose itself 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?

No when-to-use guidance, no prerequisites, and no mention of opencode_config_get as the read-side counterpart. The agent is told what to pass but not when this tool is the right choice versus reading or restarting.

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?

No annotations are provided, so the description carries the full behavioral burden. "Get" clearly signals a read, and the description usefully discloses the returned components given there is no output schema. It says nothing about side effects, permissions, or behavior when the directory is missing/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?

One sentence, front-loaded with the verb and the aggregation benefit, then the payload list. No filler; every token carries 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 one-parameter, read-only aggregator with no output schema, listing the returned components is the key thing the description must do, and it does so. Minor gap: no statement of read-only safety or failure behavior, which matters slightly more because annotations are absent.

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 sole `directory` parameter is fully documented in the schema, including the default-project fallback. The description adds no parameter detail, 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?

Specific verb ("Get") plus resource ("project context") with an explicit enumeration of the payload: project, path, VCS, config, agents. The phrase "in one call" implicitly distinguishes it from the single-purpose siblings (opencode_project_current, opencode_vcs_info, opencode_config_get, opencode_path_get, opencode_agent_list), though none are named.

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?

"In one call" hints that this is the bundled alternative to making several sibling calls, which implies usage. But there is no explicit when-to-use/when-not statement, no named alternative, and no note on when the granular sibling tools are preferable.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it only says the output is 'formatted for reading'. It does not state whether this is a read-only operation, whether it respects a limit/pagination, behavior on invalid sessions, or how large histories are handled.

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 efficient sentence with the core action front-loaded and no redundant filler. Its only weakness is brevity that shades into under-specification rather than 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?

With three parameters, no output schema, no annotations, and 33% schema coverage, the description should do more. It omits the meaning of 'limit', the sessionId requirement, and any return-format or size expectations, so an agent cannot call it confidently relative to its siblings.

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 documented in the schema. The description mentions 'session' (mapping loosely to sessionId) but says nothing about the 'limit' parameter or its units/default, leaving two of three parameters undocumented in both places.

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 verb 'Get' and resource 'full conversation history of a session' are specific enough to understand the operation, and 'formatted for reading' hints at the rendering. However, it is not distinguished from close siblings like opencode_message_list, opencode_session_get, or opencode_session_summarize, which plausibly overlap in returning session content.

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 over opencode_message_list, opencode_session_get, or opencode_session_summarize. No prerequisites, exclusions, or contextual triggers are 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?

With no annotations, the description carries the full burden. It discloses the collection window behavior (up to maxEvents within the duration), hinting at a bounded/blocking poll, but never states that this is a read-only operation, whether it blocks the caller, or what happens on timeout.

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 compact sentences with no filler, and the scope behavior is front-loaded. Efficient and on-point.

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?

No output schema and no annotations, so the description should explain the returned event shape and blocking semantics. It only gestures at the collection window, leaving the return/behavior contract thin for a 4-param polling tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% and three of four params already have schema descriptions; the only undocumented one is the scope enum. The description restates the scope choice and the maxEvents/duration relationship without adding format or default detail 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?

States a specific verb (poll) and resource (project events) plus an explicit scope option (global). No sibling in the list polls events, so differentiation is implicit rather than stated, keeping it short of 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 implies when to use the default (project) vs the global scope, but never states a when-to-use condition against alternatives or prerequisites. Usage is only implied.

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?

No annotations are provided, so the description carries the full behavioral burden, but it discloses nothing about recursion depth, ordering, error cases, or how path resolution works. '(via /api/fs/list)' is an implementation detail, not 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?

A single short sentence, front-loaded with the verb and resource. The trailing endpoint reference adds little value but costs little space.

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 no annotations, no output schema, and an undocumented 'directory' parameter, the description leaves significant gaps: return shape, path-vs-directory semantics, and listing behavior are all unspecified. It is too thin for a two-parameter tool with 50% schema coverage.

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 50%: 'path' is described but 'directory' has no description at all. The description does not explain the relationship or difference between the two parameters, which is the key ambiguity an agent faces. It fails to compensate for the coverage gap.

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?

Clear verb+resource: 'List files and directories at a path'. It is distinguishable from siblings like opencode_file_read and opencode_find_file, though it does not explicitly name them. The addition of the endpoint is harmless but not clarifying.

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 when-to-use guidance and no mention of alternatives such as opencode_find_file (search) or opencode_file_status. The agent must infer the directory-browsing role 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?

With no annotations, the description carries the full behavioral burden, yet it says nothing about error behavior (missing file, permission denied), binary/large file handling, or what content is returned. The API path hint adds little beyond the 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?

A single front-loaded sentence with no filler. The endpoint parenthetical is marginally useful rather than wasteful.

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?

No annotations, no output schema, and an undocumented 'directory' parameter leave significant gaps. For a file-read tool the agent cannot know return format, encoding, or how 'directory' interacts with 'path'.

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 50%: 'path' is described in the schema, but 'directory' is undocumented in both schema and description. The description adds no parameter meaning beyond restating the path via the endpoint template.

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 gives a specific verb+resource: reading a file's content. It is distinguishable from opencode_file_list and opencode_file_status by intent, though it does not explicitly name or contrast with those siblings.

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 on when to use this versus alternatives (e.g. find_file, file_list) is given. The agent must infer usage from the verb 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?

With no annotations, the description carries the full behavioral burden, but it only notes that results are limited to 'tracked files'. It does not say whether the operation is read-only (implied by 'Get' but unconfirmed), what the response contains, whether the directory argument scopes results, or any auth/rate constraints.

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. The parenthetical endpoint is arguably dead weight since callers cannot use it, but it is brief.

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 no output schema and zero schema coverage, so the description should explain the shape of the returned status and the role of the directory argument. It does neither, leaving meaningful gaps for an agent trying to call 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 0% for the single 'directory' parameter, and the description does not compensate — it never explains what the directory argument does or whether it is a repo root or an arbitrary path. The '/api/vcs/status' parenthetical is an implementation detail, not parameter guidance.

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 ('Get VCS status for tracked files'), which is clearer than a tautology and hints at scope (tracked files only). It does not, however, differentiate itself from the sibling opencode_vcs_info, leaving the agent to guess which VCS-related tool to use.

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 when-to-use context, no prerequisites, and no mention of alternatives such as opencode_vcs_info or opencode_review_changes. The agent gets only the raw endpoint reference and must infer the rest.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses one important limitation (unavailable on 2.x server), but says nothing about permissions, success behavior, error handling, or return format.

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 purpose and followed by a critical operational note. 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?

The tool has 5 parameters, no annotations, and no output schema. The description is very brief and leaves most parameter semantics undocumented, so an agent cannot confidently invoke it without schema guessing.

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% for 5 parameters. The description only implies that 'query' is the name to search for; it does not explain 'directory', 'searchDirectory', 'limit', or the enum values for 'type'.

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 ('Find') and resource ('files/directories') with a clear scope qualifier ('by name'). This distinguishes it from siblings like opencode_find_text (content search) and opencode_find_symbol (symbol search).

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: use this when searching for files/directories by name. The note about the 2.x server lacking the route adds a when-not condition, but no alternative tool is named for that case.

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 no annotations, the description carries the full burden. It does add a genuine behavioral trait: that the tool returns an 'unavailable' report rather than searching on 2.x servers, which is more than most definitions give. It still omits return shape, symbol semantics, and behavior on other server versions.

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 operation and followed by the critical availability caveat. No filler; every clause earns its place, though the structure is minimal given what it omits.

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 2-param tool with no annotations and no output schema, the description is thin. The availability warning is essential and present, but it says nothing about what a 'symbol' is, how 'directory' scopes the search, or what the agent should do instead.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across two parameters, so the description must compensate and largely does not. 'By name' loosely maps to 'query', but 'directory' (scope of the search) is entirely undocumented in both schema and 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?

States a specific verb and resource ('Find workspace symbols by name'), and the word 'symbol' implicitly distinguishes it from the sibling opencode_find_text and opencode_find_file. It does not explicitly name those siblings, so it stops short of 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 NOTE gives a real when-not condition by declaring the tool reports unavailable on 2.x servers, which steers the agent away. However, it never names the workable alternative (find_text/find_file) or states the conditions under which this tool is the right pick, so 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses a real environmental limitation (unavailability on 2.x servers), which is genuine value-add. It says nothing about case sensitivity, regex vs literal matching, pagination, result limits, or output format, leaving substantial behavioral gaps for a search 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 tight sentences with the purpose front-loaded and the caveat following. No filler or redundancy; only minor deduction for the slightly awkward 'NOTE:' framing.

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 no annotations, no output schema, and 0% schema description coverage on two parameters, the definition should explain parameter semantics and return behavior. The unavailability note is helpful but the description remains incomplete for correct invocation of a search 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 0%, so both 'pattern' and 'directory' are undocumented in structured form. The description mentions 'text patterns' and 'project files' but never explains whether pattern is a regex or literal string, nor how 'directory' scopes the search or what its default is. It fails to compensate for the coverage gap.

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+resource: 'Search text patterns in project files'. This is distinct from siblings like opencode_find_file and opencode_find_symbol, though it does not explicitly contrast itself with them. The core 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 note that the 2.x server has no /api/fs/find route and the tool 'reports unavailable' is an important usage caveat that tells the agent when this tool will fail. However, it names no alternatives (e.g., opencode_find_file or opencode_session_search) and gives no positive guidance on when to prefer this over sibling search 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?

With no annotations, the description must carry the behavioral burden, and it does disclose the most important trait: the call is asynchronous and returns immediately with job/session IDs rather than a result. It omits permissions, side effects, and whether the dispatched work is cancellable, leaving notable gaps for a mutation-style dispatch.

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 tight sentences; the core outcome (immediate job/session IDs) is front-loaded and the follow-up hint is second. Nothing is wasted.

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 async contract and the return identifiers are stated, which is the most important thing absent an output schema. But with 9 mostly undocumented parameters and no annotations, the definition leaves a substantial amount of operational context for the agent to guess.

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 11% (just the 'directory' param documented), yet the description explains none of the 9 parameters — not even the required 'prompt' or the relationships among agent/modelID/providerID/sessionId. It fails to compensate for the schema gap.

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 ('Dispatch a background task') plus the key outcome ('return its job/session IDs immediately'), which distinguishes it from synchronous siblings like opencode_message_send. However, it does not differentiate itself from close siblings such as opencode_message_send_async or opencode_run, so it stops short of 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?

It routes the agent to the correct follow-up tools by naming opencode_check and opencode_wait for observation, which is genuinely useful context. It does not, however, say when to choose this over the async/run siblings, so the selection guidance is only implied.

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 no annotations, the description carries the full behavioral burden and largely fails to. It does not say what 'health' means, what happens when the server is unreachable, whether it requires any auth, or how it behaves against the default vs. a named project. For a low-risk read, that is still a meaningful gap.

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 or redundancy. It is well-sized for the tool's simplicity, though it is arguably too terse to carry any real guidance.

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?

There is no output schema, so the description should convey return semantics; it gestures at 'health and version' but does not describe the shape or failure behavior. For a trivial one-parameter read tool this is minimally acceptable, not thorough.

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 the single optional directory parameter is fully documented in the schema, including its default behavior. The description adds nothing 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?

States a specific verb (Check) and resource (server health and version), so the agent knows exactly what the tool returns. It does not, however, distinguish itself from close siblings like opencode_status, opencode_check, or opencode_mcp_status, which sound equally applicable to a health/status query.

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 when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as opencode_status or opencode_check. The agent is left to infer from the name alone when this tool is preferable to the other status-like siblings.

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 no annotations, the description carries the full behavioral burden for what is clearly a destructive shutdown operation. 'Shuts it down' signals termination but says nothing about whether it is reversible, what happens to running sessions or jobs, or whether the server itself becomes unavailable afterward.

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 short sentence that front-loads the action and resource, with a parenthetical clarification. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A destructive, no-annotation, no-output-schema tool needs more than a shutdown gloss. The description omits consequences for active sessions/jobs and what the caller receives or how to recover, leaving the agent under-informed for an irreversible-seeming action.

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 already documented in the schema, including its default behavior. The description adds no parameter detail beyond that, 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?

States a specific verb (dispose) and resource (the current opencode instance), with a clarifying gloss that it shuts the instance down. An agent can distinguish it from session-level tools like opencode_session_delete, though the description doesn't explicitly contrast 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 on when to dispose the whole instance versus using opencode_session_abort, opencode_session_delete, or simply ending work. No prerequisites or consequences are stated to help the agent choose this 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?

With no annotations, the description carries the full behavioral burden. 'List' implies a read-only, non-destructive call, but it says nothing about permissions, whether results are paginated, or what happens if no integrations are registered. Beyond the verb, little behavioral context is added.

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 with zero filler, stating the resource up front. Nothing could be trimmed without losing 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 one-parameter list tool with no output schema, the description is minimally adequate: the agent knows it lists integrations on the server with an optional project directory. It leaves the return structure and any auth/scope caveats unspecified, which keeps it at minimum-viable rather than complete.

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 single optional 'directory' parameter and its default are already fully documented in the schema. The description adds no extra meaning about the parameter, 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?

States a specific verb and resource ('List registered integrations') and parenthetically disambiguates the term as plugins, which is genuinely useful since no sibling tool covers integrations. It doesn't need to differentiate from siblings because none are close, but it also doesn't say anything about scope or return shape beyond 'on the server'.

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 on when to call this versus alternatives (e.g., mcp_status, skill_list, provider_list) or whether it is needed before other operations. Usage is inferable from a plain list operation, but the description provides none explicitly.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Abort' implies a terminating mutation, but the description never states reversibility, required permissions, effect on in-flight work, or error/not-found behavior, which matters for a cancel operation.

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 short, front-loaded sentence with no padding, which is structurally fine. It is terse to the point of under-specification rather than wastefully verbose, so it avoids penalty but earns no praise.

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 no annotations, no output schema, partial parameter coverage, and a crowded sibling namespace, the description is too thin. It does not disclose the outcome of the abort or how it differs from the many session-permission and abort-adjacent siblings.

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 only 50% ('sessionId' is undocumented) and the description adds no parameter meaning at all. 'Session owned by a task' hints at a session identifier, but neither the schema nor the description explains how sessionId relates to the 'task' framing or what directory does.

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 gives a specific verb ('Abort') and a scoped resource ('the OpenCode session owned by a task'), which is more than a tautology. However, the tool is named 'job_cancel' yet describes aborting a session, and a sibling 'opencode_session_abort' exists, leaving the boundary between the two unclear. An agent cannot confidently tell this apart from the sibling from the description alone.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as opencode_session_abort or opencode_job_get. The agent is left to infer when cancellation is appropriate versus stopping a session directly.

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?

No annotations are provided, so the description carries the full burden. It reveals that output includes status and captured response text, but says nothing about read-only nature, whether calls block, how pollMs/deadline interact, or what happens when the job is still running or already finished.

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; the core action is stated immediately. It is short rather than padded, though brevity here shades into under-specification that is penalized in other dimensions.

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 five-parameter, zero-required, no-annotation, no-output-schema tool, the description is too thin. Nothing explains the polling/timeout mechanics implied by pollMs and deadline, nor the relationship between jobId and sessionId, leaving an agent unable to call it 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 only 20% (just 'directory'), and 0 of 5 parameters are required, yet the description explains none of them. 'By session' faintly gestures at sessionId, but jobId, pollMs, and deadline — the parameters that actually control behavior — are never clarified.

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 (observe/get) and resource (a dispatched task/job), plus what comes back (status and captured response text). It is distinguishable from its only functional sibling opencode_job_cancel, though the phrase 'by session' sits awkwardly against the schema's primary jobId parameter and is never reconciled.

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 when-to-use guidance is given, and no alternatives are named. An agent is left to infer that this polls a previously dispatched job and should be compared against opencode_job_cancel or opencode_wait; nothing in the text routes 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?

With no annotations provided, the description carries the full behavioral burden and delivers almost none of it. It does not say whether the entry is persisted or ephemeral, whether it requires an active session/project, what effect each severity level has, or whether it returns anything. Only the minimal mutation intent ('write') is conveyed.

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 short sentence that is front-loaded and free of filler. It is efficient, though its brevity reflects under-specification rather than disciplined conciseness.

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 mutation tool with five parameters, 20% schema coverage, no annotations, and no output schema, so the description must do more than one sentence. Nothing about side effects, required context, or parameter meaning is covered.

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 20% (just the optional 'directory' parameter), and the description adds no parameter meaning at all. It never explains 'service', 'message', the severity enum, or the nested 'extra' object, leaving four of five parameters undocumented across both sources.

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 on the opencode server), so an agent knows exactly what the tool does. It does not need heavy sibling differentiation since no other sibling deals with log writing, but it also makes no attempt to distinguish itself from related diagnostic tools like opencode_health or opencode_check.

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, no mention of prerequisites, and no indication of when logging is appropriate or inappropriate. The agent must infer usage entirely from the tool 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. For a mutation tool it says nothing about whether the server is persisted or only lives for the current instance, whether the server is started/validated on add, whether adding an existing name overwrites, or what the response looks like. 'Dynamically' hints at a runtime-only effect but is never defined.

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 short sentence is front-loaded and waste-free, but it is under-specified rather than concise: for a mutation tool with a free-form config object, one line leaves the critical detail (config structure) entirely unaddressed.

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?

A mutating tool with no annotations, no output schema, an undocumented nested 'config' object, and a required-name collision question is left almost entirely unexplained. The description gives an agent nothing needed to actually construct a valid call.

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 33% and only 'directory' is documented; 'name' and 'config' rely entirely on the schema. 'config' is a free-form nested object with no sub-schema and no description anywhere, so an agent has no way to know the required shape (command, args, env, type, etc.), and the description does not compensate for that gap.

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 (add) and resource (MCP server) with the qualifier 'dynamically', which conveys runtime registration rather than config-file editing. It is clear on its own, but it does nothing to distinguish itself from the only adjacent sibling, opencode_mcp_status, or to explain what 'dynamically' means operationally.

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 when-to-use guidance, no mention of prerequisites, and no reference to any alternative (e.g. editing config via opencode_config_update versus using this tool). The word 'dynamically' is the only implied context, and it is not explained.

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?

No annotations are supplied, so the description carries the full burden. It does disclose scope ('all MCP servers'), and the word 'status' implies a non-mutating read, but it says nothing about return shape, ordering, or whether a directory-scoped call reports servers configured elsewhere.

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, front-loaded with the verb and resource, with no filler or redundancy. Nothing could be removed without losing 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 status query with one optional, fully documented parameter and no output schema, the description adequately conveys what is being queried. It is slightly thin on how directory scoping affects results, but nothing essential to invoking the tool 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% and the single optional 'directory' parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no extra meaning about how directory selection affects the reported MCP server list.

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 the status') and a precise resource ('all MCP servers configured in opencode'), which clearly separates it from the write-side sibling opencode_mcp_add and from the many session/message tools. It does not explicitly name any sibling, so it lands at 4 rather than 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?

There is no when-to-use guidance, no prerequisite, and no mention of an alternative or a 'use X instead' condition. The description only states what the tool does, leaving the agent to infer that this is the diagnostic counterpart to opencode_mcp_add.

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?

No annotations are provided, so the description carries the full behavioral burden. It says nothing about whether the call is read-only, what happens when the message or session does not exist, required permissions, or the shape of the returned details.

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 short, front-loaded sentence with no filler or redundancy. It is efficient, though its brevity comes at the cost of under-specification rather than over-explaining.

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 no annotations, no output schema, and two of three parameters undocumented, the description is too thin for an agent to call this correctly. It omits return format, error behavior, and any identifier expectations.

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 documented; sessionId and messageId are bare). The description mentions "message" and "session" but adds no format, scope, or identifier meaning beyond what the parameter names already imply, so it fails to compensate for the coverage gap.

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 details") and resource ("a specific message in a session"), so an agent can tell it apart from opencode_message_list. It does not explicitly name the sibling it is distinguished from, keeping it short of 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?

No when-to-use guidance or alternatives are given. The agent must infer from the name that this fetches a single message versus the bulk opencode_message_list, but the description never states that condition or any prerequisites.

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 no annotations at all, the description carries the full behavioral burden. It hints that output is 'formatted roles and content' but says nothing about ordering, defaults, truncation, or pagination behavior, and 'all messages' directly conflicts with the 'limit' parameter defined in the 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?

A single well-formed sentence with no filler and a clear front-loaded verb. It is efficient, though the brevity is partly under-specification rather than true economy.

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?

No output schema and no annotations mean the description must explain return shape, ordering, and limits, and it does none of these. For a three-parameter read tool with an ambiguous sibling set, this leaves the agent with too many open questions to invoke it 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 coverage is 67% — limit and directory are documented in the schema, but sessionId has no description anywhere. The description adds no parameter meaning and actively muddies 'limit' by claiming the tool lists 'all messages', so it does not compensate for the coverage gap.

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 gives a specific verb+resource (list messages in a session) plus a hint at presentation ('formatted roles and content'), which is clearer than the bare name. However, it does not distinguish itself from the sibling opencode_message_get, which an agent would need in order to choose between listing and fetching 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?

There is no statement of when to use this tool versus opencode_message_get, opencode_session_search, or opencode_session_todo. No prerequisites (e.g., a valid session must exist) are mentioned; the agent must infer the context entirely.

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?

No annotations are provided, so the description carries the full burden. It does disclose one genuinely useful behavioral trait beyond the schema: the call blocks until the AI reply arrives. However, it says nothing about error/timeout behavior, permission requirements, or what happens with noReply=true versus the default.

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 well-formed sentence with the action front-loaded and no filler. It is efficient, though arguably terse for a 10-parameter tool, so it stops short of ideal.

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 10-parameter, annotation-free tool with no output schema and 90% undocumented parameters, one sentence is far too thin. An agent gets no sense of model/agent selection, reply content shape, or failure modes before invoking it.

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?

Only 1 of 10 parameters (directory) has any schema description, so coverage is 10% and the description adds no parameter meaning at all. Undocumented fields such as agent, modelID, providerID, variant, format, system, and noReply are left entirely to guesswork, which does not compensate for the schema gap.

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 (send) and resource (prompt to a session) plus the outcome (wait for the AI response). The waiting clause implicitly distinguishes it from the sibling opencode_message_send_async, but the sibling is never named, so the differentiation is left to inference.

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 only implied: 'wait for the AI response' signals a blocking call versus the non-blocking opencode_message_send_async, but there is no explicit when-to-use/when-not-to-use statement, no mention of prerequisites (session must exist), and no guidance on choosing between the two send 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose a genuinely valuable trait — that 2.0.30 falls back to a synchronous /prompt call that may block — but it omits auth requirements, error behavior, and return-format details beyond the messageId.

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, front-loaded with the core action and immediately followed by the important caveat. Minimal waste, though the NOTE reads slightly run-on.

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 8 parameters and 13% schema coverage and no output schema, the description covers only the async/fallback behavior. Most parameters and the practical invocation details remain undocumented anywhere.

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 13%: 8 parameters, with only 'directory' documented. The description adds no meaning for text, agent, format, modelID, variant, sessionId, or providerID, so it fails to compensate for the coverage gap.

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 ('Send a prompt asynchronously') and clarifies the return value ('return its messageId for opencode_wait'), which makes the async workflow legible. It does not explicitly name the sibling opencode_message_send as the synchronous alternative, so differentiation is only implied.

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 mention of returning a messageId 'for opencode_wait' implies the intended two-step workflow, but there is no explicit when-to-use vs opencode_message_send guidance or when-not condition. Usage is left to inference.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'Get' implies a read-only, idempotent retrieval, but the description says nothing about return shape, whether the server default project matters, or any error conditions.

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, which is exactly the right shape for a trivial getter. It is well structured, though the terseness borders on under-specification for a tool with no other supporting fields.

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 read tool with no output schema, saying it returns 'the current working path' is just barely sufficient. It omits how the path relates to opencode_project_current and what the 'server default project' fallback means, which are the main ambiguities an agent would face.

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 the single optional 'directory' parameter already documents its default behavior, so the schema does the heavy lifting. The description adds no extra meaning (e.g., what changes when directory is supplied), which is the expected baseline when coverage is complete.

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+resource (get the current working path of the opencode server) that an agent can act on directly. However, it never distinguishes itself from the closely named sibling opencode_project_current, so the agent cannot tell which one to reach 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?

There is no when-to-use guidance and no mention of alternatives, even though opencode_project_current and opencode_vcs_info cover adjacent territory. The agent is left to infer context entirely 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?

No annotations are provided, so the description carries the full behavioral burden. "List" implies a read-only, non-destructive operation and the scope is disclosed, but nothing is said about ordering, volume, pagination, or what happens if no requests are pending.

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 with no filler, and the resource/scope comes first. The second sentence is terse enough to be slightly ambiguous about whether it is a routing instruction or a return-value note.

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, read-only list tool with no output schema or annotations, the description covers purpose and scope adequately and points at the follow-up tool. The only gap is the absence of detail on result volume or ordering.

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?

There is a single optional parameter with 100% schema description coverage, so the schema already explains the directory scope and its default. The description adds no syntax or format detail beyond that, which matches the baseline of 3 when 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?

States a specific verb and resource ("List pending permission requests") plus scope ("across all sessions"), which separates it from per-session tools. It also names the sibling opencode_session_permission as the follow-up, though the relationship between the two is implied rather than explicit.

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?

"Respond with opencode_session_permission" routes the agent to the right next tool once requests are listed, which is useful contextual guidance. However, it never states when to call this versus per-session alternatives, and there are no exclusions or prerequisites described.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure for a read tool. It does not state that this is a side-effect-free read, what happens when no project is active, or how the optional directory argument changes the result.

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 short, front-loaded sentence with no wasted words. It is appropriately sized for a simple getter, though the brevity edges toward under-specification rather than pure efficiency.

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?

There is no output schema and no annotations, so the description could reasonably explain the return shape or what 'active project' means, but it does not. For a zero-required-parameter getter it is minimally adequate rather than complete.

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 fully documented in the schema. The description adds no meaning beyond it, 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?

States a specific verb ('Get') and resource ('current active project'), so an agent understands this is a read of the active project state. However, it does not distinguish itself from siblings like opencode_project_list, opencode_project_init, or opencode_path_get, which are plausible alternatives for project-related reads.

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 when-to-use guidance, no conditions, and no mention of alternatives. An agent cannot tell from this text why it would call this instead of opencode_project_list or opencode_path_get.

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 no annotations, the description carries the full burden. It implies filesystem mutation on the host and session isolation, but does not state whether an existing directory is reused or overwritten, what permissions are required, whether parent directories are created, or what is returned. For a host-side mutation this is a significant gap.

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 front-loaded sentence with no filler. It is appropriately sized for a single-parameter tool, though the brevity contributes to the unresolved 'create or open' semantics rather than resolving them.

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?

Minimum viable: the sole parameter is documented and there is no output schema to explain. However, with no annotations and no return-value description, an agent lacks the mutation semantics (reuse vs. overwrite, error conditions, resulting project handle) needed to invoke this 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 coverage is 100% and the single parameter's description ('Absolute path to create/open') duplicates the schema text verbatim, so the description adds no new meaning. Baseline 3 applies when the schema does the work.

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 ('Create or open') and resource ('a project directory on the MCP host') with the intended purpose (isolated OpenCode session). It is clearly distinguishable from opencode_project_list/current, but the 'create OR open' duality is left unresolved, so the agent cannot tell which behavior fires for a given path.

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 when-to-use or when-not-to-use guidance and no alternatives named, despite siblings like opencode_session_init and opencode_project_list that a planner could confuse with this. The phrase 'for an isolated OpenCode session' only weakly implies the trigger condition.

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?

No annotations are provided, so the description carries the full behavioral burden. It says nothing about whether this is a read-only operation, whether the server must be authenticated/running, or what the response contains; for a server-backed list call that is a meaningful gap.

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. It is efficient, though arguably too terse given the disclosure gaps 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 a fully documented schema this is minimally viable, but with no output schema the description should indicate what a 'project' record looks like or what the response returns.

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 has 100% schema description coverage, so baseline is 3. The description adds nothing about 'directory' and its claim of 'all projects' slightly undercuts the parameter's narrowing behavior, but the schema itself is self-sufficient.

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 (List) and resource (projects known to the opencode server), which is clear on its own. It does not distinguish itself from the project-related siblings (opencode_project_init, opencode_project_current), leaving the agent to infer the difference.

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 rather than opencode_project_current or opencode_project_init. The phrase 'all projects' implies enumeration, but nothing states prerequisites, pagination, or the alternative for a single project.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read, but there is no disclosure of auth requirements, rate limits, response shape, or whether 'all providers' includes configured versus unconfigured providers.

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. Every word contributes to stating the tool's purpose and scope.

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 one-parameter read tool with no output schema, the description states the purpose adequately. However, with no annotations and no output schema, it omits any behavioral context or return-value guidance that would make the definition fully self-contained.

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 optional 'directory' parameter, so the input schema already documents its meaning. The description adds no further parameter semantics, which matches the baseline of 3 when 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 gives a specific verb and resource: 'Get available authentication methods for all providers.' This clearly distinguishes it from provider_list, provider_models, and auth_set, though it does not explicitly name those siblings.

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 such as opencode_provider_oauth_authorize, opencode_provider_oauth_callback, or opencode_auth_set. The agent must infer the workflow context on its own.

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 no annotations, the description carries the full load. It usefully discloses that results include a connection status field, but says nothing about read-only semantics, auth requirements, or ordering/pagination. Adequate for a low-risk list operation, but thin given zero annotation coverage.

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; the resource and the key return attribute are 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 no-argument-heavy read tool with no output schema, the description is nearly sufficient; it even hints at return content via 'connection status'. It lacks only disambiguation from sibling provider tools, which is a minor gap at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the single 'directory' parameter is already fully documented by the schema (optional, defaults to server default project). The description adds no extra semantics, 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?

States a specific verb (List) and resource (configured providers) plus a scope qualifier (with connection status). Clear on its own, but it never distinguishes itself from the closely-named sibling opencode_config_providers, which an agent could easily confuse for this.

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 when-to-use framing, no prerequisite notes, and no routing to alternatives such as opencode_config_providers or opencode_provider_models. Usage is only inferable from the verb 'List'.

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 no annotations, the description carries the full behavioral burden, yet it gives nothing beyond the word 'List'. It does not state that this is a read-only operation, that providerId must reference a valid/configured provider, or whether results are paginated (the limit param hints at paging but this is not explained). For a tool with zero annotation coverage this is a notable gap.

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 efficient sentence with the resource front-loaded and no filler. It is perhaps slightly under-specified rather than concise, but there is no wasted 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?

For a simple listing tool with no output schema, the description is minimally adequate but leaves open what a returned model entry contains and how limit interacts with paging. It is complete enough to call the tool, but thin on context an agent would find useful.

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 67%: limit and directory are documented in-schema, but the required providerId has no schema description. The description only implies providerId via 'for a specific provider' and adds nothing about limit or directory behavior. Baseline 3 applies since the schema does most of the work and the description adds marginal 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?

States a specific verb (List) and resource (models) scoped to a provider, which is clear enough to distinguish from siblings like opencode_provider_list (providers) and opencode_provider_auth_methods. However, it never names those siblings or otherwise anchors the distinction, so the differentiation is inferred rather than stated.

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 when-to-use guidance, no prerequisites, and no mention of how it relates to opencode_provider_list or opencode_tui_open_models. The agent must infer when this tool is appropriate purely from the name and one-line 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?

With no annotations, the description carries the full behavioral burden but discloses nothing beyond the verb. It does not state that initiation typically yields an authorization URL/token, that a callback is expected next, or whether state is mutated server-side.

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 zero filler. It is efficient, though the brevity is partly the under-specification problem rather than disciplined conciseness.

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-initiation tool with a nested object parameter, no output schema, and no annotations, the description is too thin. It omits the flow context (callback follow-up) and any parameter meaning an agent needs 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 0% for three parameters, and the description only vaguely implies providerId. The 'inputs' object and numeric 'method' parameter are completely unexplained, so the description fails to compensate for the coverage gap.

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 ('Start') and resource ('OAuth authorization') tied to a provider, so the action is clear. It does not differentiate itself from the closely related siblings opencode_provider_oauth_callback, opencode_provider_auth_methods, or opencode_auth_set, which an agent must disambiguate between.

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 on when to use this versus the sibling auth tools, and no mention of prerequisites such as first checking auth methods. The multi-step OAuth flow (this tool then oauth_callback) is left entirely implicit.

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 no annotations, the description carries the full behavioral burden and does not deliver: it says nothing about whether a token is stored, whether the provider must already be configured, side effects, or error conditions. Only the vague action 'handle' is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no padding, which is structurally fine but so terse that it functions as under-specification rather than conciseness.

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 unexplained nested object payload, no annotations, and no output schema, the description is incomplete — it omits the callback data contract, prerequisites, and outcome, all of which an agent needs to 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 0%, and one parameter is an untyped nested object (callbackData) whose expected contents are entirely unexplained. The description adds no information about either providerId or callbackData, leaving the caller to guess the payload shape.

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 resource (OAuth callback) and roughly what happens ('handle'), but the verb is vague and it never distinguishes itself from the sibling opencode_provider_oauth_authorize or explains the callback's role in the flow. An agent can infer intent from the name, but the description adds little beyond it.

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 on when this is invoked versus opencode_provider_oauth_authorize, nor any stated prerequisite (e.g., that an authorize call must precede it). The usage is only implied by the word 'callback'.

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 no annotations, the description carries the full disclosure burden and does well on side effects: it creates a temporary session, sends a prompt, and cleans up, so the agent knows this is not a passive read. It omits other important traits, notably that this makes a real model call (latency/cost implications), any auth prerequisites, and whether cleanup is guaranteed on failure.

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 tight sentences with zero filler. The purpose leads and the implementation detail follows, so the agent gets the 'what' before the 'how'.

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?

There is no output schema and no annotations, so the description should say what a test result looks like (pass/fail, error surface) and clarify the undocumented parameters. The mechanism description is unusually helpful, but the return contract and most parameter meanings remain unspecified.

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 20% (just directory), and the description names no parameters at all. providerId is required but unexplained in both places, and format/modelID/variant are opaque; the description does nothing to compensate for the coverage gap.

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 (test) and resource (provider) and immediately describes the mechanism: a temp session with a trivial prompt. It is trivially distinguishable from siblings like opencode_provider_list, opencode_provider_models, and opencode_provider_auth_methods, which inspect configuration rather than exercising the provider.

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?

"Quick-test whether a provider is working" gives clear situational context for when to reach for this tool. It stops short of naming alternatives (e.g., use provider_list to merely check configuration) or stating when not to use it, but the intended moment of use is unambiguous.

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?

No annotations are provided, so the description carries the full behavioral burden. 'List' weakly implies a read-only operation, but the description says nothing about permissions, whether it is scoped to a server/session instance, or what happens when no ptys are open.

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 short, front-loaded sentence with zero filler, which is appropriate for a simple list tool. It is efficient but almost too sparse to earn a top score.

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 no output schema, the description should hint at what a listing returns (pty id, attached command, status), and it does not. For a low-complexity, single-optional-param tool this is acceptable but leaves a real gap around return shape and scope.

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 already documents its default behavior, so the schema does the heavy lifting. The description adds no extra meaning (e.g. why pty listing would differ per directory), 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?

States a specific verb (List) and resource (open pseudo-terminals managed by opencode), which is unambiguous and distinguishable from the session/message/file siblings. It stops just short of 5 because it never explains what a 'pseudo-terminal' means in this product or what a listed entry represents.

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 when-to-use guidance, no prerequisites (e.g. must a session exist first?), and no mention of alternatives such as shell_execute or tui tools. The agent is left to infer everything about triggering conditions.

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?

No annotations are supplied, so the description carries the whole burden. It does add one genuine behavioral fact — the tool may not exist on this build — which the agent would otherwise have no way to know. It says nothing about return shape, pagination, or permission requirements for a read operation, so the disclosure is thin.

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, and the availability caveat is parenthetically placed so it does not bury the core purpose. It is efficient, though borderline under-specified.

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 two-parameter list tool with no output schema this is close to sufficient, and the build-availability warning helps. Still missing is any notion of what a 'question' contains or how sessionId narrows the result set, which an agent needs to invoke it precisely.

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 50% (directory is documented, sessionId is bare). The description adds nothing about either parameter, so the undocumented sessionId and its scoping effect on 'pending questions' remain unexplained — the description fails to compensate for the coverage gap.

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?

Names a specific verb and resource ('List pending OpenCode questions'), which is clearly distinct from the neighboring opencode_question_reply and opencode_question_reject tools. It does not, however, differentiate itself from other list-style siblings beyond the 'questions' resource noun.

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 'pending' implies the natural context (check outstanding questions before replying or rejecting), and the 'may be unavailable on this build' caveat is useful operational guidance. But no explicit when-to-use statement or named alternatives 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?

With no annotations, the description carries the full behavioral burden, yet it says nothing about what rejecting actually does: whether the pending request is cancelled permanently, how the waiting agent/requester is notified, or whether the action is reversible. For a state-changing terminal action this is a real gap.

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 zero padding. It is efficiently sized, though the terseness is partly under-specification rather than disciplined concision.

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 mutation tool with no annotations, no output schema, and an undocumented required parameter, the definition is too thin. An agent lacks the rejected-question lifecycle, the requestId source, and any permission or side-effect context needed to call it 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 only 50%: 'directory' is documented as optional with a default, but the required 'requestId' has no description in the schema and the description text explains neither its format nor where to obtain it. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap.

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 ('Reject') and resource ('a pending OpenCode question'), so the purpose is immediately legible. However, it never names the obvious sibling alternatives (opencode_question_reply or opencode_question_list), so the agent gets no explicit differentiation help.

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 when-to-use or when-not-to-use guidance and no mention of alternatives. 'Reject' vs 'reply' for a pending question is exactly the selection the agent needs to make, and the description supplies nothing to route that decision.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: it does not say whether answering resumes a blocked session, whether the answer must match the number/shape of questions asked, or whether it is final and irreversible. For a mutation-style tool with zero annotation coverage this is a substantial gap.

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 zero filler, which is well-formed prose. It is arguably undersized for the complexity of the operation, but the sentence itself 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?

With no annotations, no output schema, only one of three parameters documented, and an unusual nested input shape, the definition leaves an agent unable to construct a correct call with confidence. More detail on requestId provenance and the answers structure is needed.

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 33%: only the optional 'directory' parameter is documented, while the required 'requestId' and the non-obvious nested 'answers' array (array of arrays of strings) are unexplained in both schema and description. The description never describes the answer format, so it fails to compensate for the coverage gap.

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 (Answer) and resource (a pending OpenCode question), which is clear enough to distinguish it from opencode_question_reject and opencode_question_list by verb alone. It does not, however, explicitly name those siblings or clarify scope versus the ambiguously named opencode_ask/opencode_reply.

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 when-to-use guidance: nothing says a requestId must first be obtained from opencode_question_list, that only a 'pending' question can be answered, or that opencode_question_reject is the alternative. The word 'pending' is the only usage signal.

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 no annotations, the description carries the full behavioral burden but only says it 'lists'. It doesn't disclose whether the operation is read-only, requires auth, paginates, or what the result contains. Minimal behavioral signal for a tool with zero annotation coverage.

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 tight sentence with the verb and resource front-loaded and no filler. It is efficient, though its brevity contributes to the ambiguity noted elsewhere rather than being maximally informative.

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 one-optional-param list tool with no output schema, the description is barely adequate. It omits what 'reference files/resources' means and what gets returned, which an agent would need to invoke it with confidence.

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 fully documented there as optional and defaulting to the server default project. The description adds no parameter detail, 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?

States a specific verb 'List' and a distinct resource ('reference files/resources available to opencode'), which separates it from siblings like opencode_file_list and opencode_project_list. However, it doesn't clarify what 'reference files/resources' actually are, leaving some ambiguity about the intended content.

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 when-to-use guidance, prerequisites, or named alternatives. An agent must infer that this is used when it needs opencode's reference material rather than project files, which the text never states.

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 no annotations, the description carries the full behavioral burden and falls short. It does not say whether the call blocks for a response, whether it is synchronous versus the async sibling, what happens if the session is idle or running, or what the response looks like.

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 is efficient. It is arguably too terse for an 8-parameter tool, but there is no wasted text.

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 8-parameter tool with no annotations, no output schema, and 13% schema coverage, one sentence is far too thin. The agent lacks enough context on behavior, return, and parameters to 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 only 13% (just the directory param), yet the description mentions none of the parameters. Six parameters (agent, format, modelID, variant, providerID, sessionId) are undocumented in both the schema and the description, so the description fails to compensate for the coverage gap.

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 gives a clear verb+resource: sending a message to an existing session. However, it does nothing to distinguish opencode_reply from near-identical siblings such as opencode_message_send, opencode_message_send_async, opencode_fire, or opencode_ask, leaving the agent unable to tell which one to pick.

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 indication of when to use this tool versus the many message-sending and session-interaction siblings. 'Follow-up' hints at a continuing session but no prerequisite, exclusion, or alternative is named.

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?

No annotations are provided, so the description carries the full burden. 'Get a formatted summary' implies a non-destructive read, which is reassuring, but the description says nothing about permissions, scope, or whether the summary is a diff, stats, or a list. For a read-only tool the risk is low, so this is adequate rather than poor.

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 wasted words. It is efficient, though the brevity is part of why it lacks usage and parameter detail.

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 no annotations, no output schema, and only 33% parameter coverage across three parameters, the description is too thin. It does not explain the summary's shape or how to narrow results by message.

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 only 33%. The description implies a session scope (covering the required sessionId) but adds no meaning for messageID or directory, both of which are undocumented in the schema as well. It does not compensate for the coverage gap.

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 clear verb (Get) plus resource (formatted summary of all file changes in a session), so an agent understands the operation. It does not, however, differentiate itself from the sibling opencode_session_diff, which sounds like an obvious overlapping alternative.

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 statement of when to use this versus opencode_session_diff or opencode_file_status, and no prerequisites or exclusions. The agent must infer the choice 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?

With no annotations present, the description carries the full burden. It usefully discloses two behaviors beyond the schema: the call is synchronous ('wait for its correlated response') and an observation timeout does not kill the remote session. However, it omits side effects/mutations, permission or auth requirements, and idempotency, which are significant for a task-execution 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 tight sentences, action front-loaded ahead of the return/timeout caveat, with no filler. Appropriately sized for what it chooses to say, though minimal for a 10-parameter 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 10-parameter execution tool with no annotations and no output schema, the description is far too thin. It clarifies return shape (job snapshot) and timeout semantics but leaves the purpose of most parameters, execution side effects, and the relationship to sibling session/job tools undeclared.

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?

Ten parameters with only 10% schema description coverage (just 'directory'), and the description supplies no parameter meaning at all. It does not compensate for the large undocumented surface (agent, modelID, providerID, variant, sessionId, maxDurationSeconds).

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 concrete verb+behavior: send a task, wait for its correlated response, and return a job snapshot. This distinguishes it from async siblings implicitly, but the generic word 'task' and lack of any named alternative keep it from being fully differentiated.

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 versus opencode_message_send, opencode_message_send_async, opencode_wait, or opencode_job_get. The description implies a synchronous execution path but never states the condition that selects it over the async 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states that it aborts a running session; it omits any mention of side effects, reversibility, required permissions, or return behavior—gaps that are significant for a mutation/action 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?

The description is a single, front-loaded sentence with no wasted words. While extremely brief, it is structurally efficient, though its terseness arguably leaves the tool under-specified.

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 an action tool with no annotations, no output schema, and incomplete parameter documentation, the description is far too sparse to be complete. It provides only the core action and nothing about execution context, results, or prerequisites.

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 50% (only the 'directory' parameter is documented). The description adds no parameter meaning at all; it does not mention 'id' or 'directory', so it fails to compensate for the undocumented 'id' 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 states a specific verb ('Abort') and resource ('session') and adds a state constraint ('running'). It is clear what the tool does, but it does not distinguish itself from siblings like opencode_session_delete or opencode_job_cancel.

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, when not to use it, or what alternatives exist. It simply states the action without any contextual or comparative information.

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 no annotations, the description carries the full behavioral burden, yet it discloses almost nothing: it doesn't say whether the call is read-only, whether it recurses into grandchildren, what constitutes a 'child' (forked/subsession), or what happens when the parent has no children. Read-only semantics are only implied by 'Get'.

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 short sentence with no padding, so there is no waste, but it is under-specified rather than concise — the terseness leaves the agent with no actionable detail beyond the name.

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 two-parameter tool with no annotations, no output schema, and one undocumented parameter, the description is too thin: it never clarifies the parent/child session model or what the response contains, leaving the agent to guess at semantics.

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 50%: 'directory' is documented in the schema but 'id' carries no description, and the tool text adds nothing about which id is expected (session id vs. parent id) or how directory affects resolution. The description does not compensate for the uncovered 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 states a concrete verb and resource: 'Get child sessions of a session,' which is more specific than a generic list or get. However, it offers no differentiation from adjacent siblings such as opencode_session_list, opencode_session_get or opencode_session_fork, which an agent must distinguish on its own.

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 call this instead of opencode_session_list, opencode_session_get, or opencode_session_fork, nor any note about prerequisites such as needing a valid parent session id. Usage must be inferred entirely 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?

With no annotations, the description carries the full behavioral burden, yet it says nothing about persistence, whether parentID must reference an existing session, permission requirements, or what the call returns. "Create" implies mutation but no side effects or lifecycle details are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and followed by the optional inputs. It is efficient, though the brevity edges toward under-specification rather than deliberate conciseness.

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?

There is no output schema and no annotations, so the description should explain what a caller gets back (a session identifier for subsequent opencode_message_send or opencode_session_get calls) and whether parentID affects session behavior. Neither is covered, leaving the definition thin for a creation 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%, so the schema already documents all three parameters including the directory field the description omits. The mention of parentID and title adds no syntax or constraint information beyond what the schema states, 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?

States a specific verb and resource ("Create a new session") so the operation is immediately identifiable. It does not distinguish itself from sibling creators such as opencode_session_fork, which also produces a session, so it stops short of 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 gives no when-to-use context and never names the alternative (opencode_session_fork) for deriving a session from an existing one. The only guidance is the word "Optionally" attached to parentID and title.

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 no annotations, the description carries the full behavioral burden. 'All its data' hints at the blast radius, but it says nothing about irreversibility, required permissions, or side effects on related sessions/messages — critical omissions for a destructive operation.

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 short, front-loaded sentence with no filler. It is appropriately sized, though its brevity reflects under-specification rather than tight editing.

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?

A destructive tool with no annotations, no output schema, and half its parameters undocumented needs far more than a single sentence. An agent cannot tell from this definition what is destroyed beyond the session record or whether the action can be undone.

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 only 50%: 'directory' is documented in the schema while 'id' has no description anywhere. The description adds no meaning to either parameter, so it does not compensate for the coverage gap.

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 (delete) and resource (session) plus the scope of deletion ('all its data'). It is distinguishable from reversible siblings like opencode_session_abort or opencode_session_revert, though it never names those siblings 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite the sibling set containing abort, revert, unrevert, and unshare, which are the natural non-destructive alternatives an agent should consider first.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read operation via 'Get' but says nothing about what the diff contains (git patch, file changes, unified format), whether it requires a shared/forked session, how large it can get, or what happens for sessions with no changes.

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 with zero filler, and the core action is front-loaded before the optional modifier. Every clause 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?

With no annotations, no output schema, and partial parameter documentation, the description leaves an agent guessing at the diff's format and semantics. For a tool whose entire value is the returned diff, this is under-specified.

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 only 33% (only 'directory' is documented), so the description must compensate. It partially does: 'for a session' clarifies the required id and 'optionally for a specific message' clarifies messageID's role and optionality. However, it adds no detail on the id format or what 'directory' scoping does, leaving gaps for two of three 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 and resource ('Get the diff for a session') and adds the optional narrowing to a specific message. It is immediately distinguishable from siblings like opencode_session_get or opencode_session_status, though it never explicitly contrasts itself with opencode_review_changes.

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 when-to-use guidance, no prerequisites, and no named alternative. The phrase 'optionally for a specific message' hints at two invocation modes but doesn't say when to prefer one over the other or how this differs from review_changes.

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 no annotations, the description carries the full burden. It says nothing about whether messages are copied, what happens to the source session, permissions required, or whether the new session ID is returned – important gaps for a session-mutating 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?

A single front-loaded sentence with zero filler; the fork action leads and the optional message anchor follows. Efficient, though its brevity contributes to the other gaps.

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 fork operation with no annotations, no output schema, and one-third parameter coverage, the description omits too much – no result handling, no copied-state explanation, no defaults for the optional parameter.

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 only 33%, with just 'directory' documented. The description does usefully explain what messageID means (the fork point), partially compensating, but 'id' and the return semantics of directory remain unelaborated.

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 ('Fork an existing session') and clarifies the message-level granularity, which inherently separates it from opencode_session_create. It doesn't explicitly name a sibling, so it stops short of 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?

There is no when-to-use guidance, no mention of when to prefer this over opencode_session_create, and no prerequisites (e.g. session must exist). The word 'optionally' hints at a default behavior but doesn't explain 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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about error behavior for a missing/invalid ID, required permissions, or what 'details' actually comprises. For a lookup tool with zero annotation coverage this is a substantial gap.

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 well-formed sentence with the resource front-loaded and no filler. It is efficient, though its brevity stems partly from saying too little rather than from tight editing.

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 no annotations, no output schema, one of two parameters undocumented, and roughly twenty session-related siblings, the description is far too thin for an agent to confidently select and invoke this tool rather than a neighbor.

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 50%: the 'directory' parameter is documented, but 'id' has no schema description. The phrase 'by ID' weakly signals that the id is the session identifier, but adds no format, source, or constraint information to compensate for the undocumented 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?

It states a specific verb and resource ('Get details of a specific session by ID'), so the agent knows it retrieves a single session. However, it offers no differentiation from siblings such as opencode_session_status, opencode_session_children, or opencode_session_diff, which also read a single session's state.

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 choose this over opencode_session_list (enumerating sessions), opencode_session_status (runtime state), or opencode_session_diff (changes). The agent must infer the distinction purely from tool names.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the long-running nature (30-60s+), which is real behavioral value, but it omits whether an existing AGENTS.md is overwritten, whether analysis is read-only, and what side effects occur.

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, no filler, with the core action and the latency warning both front-loaded. Nothing here needs trimming.

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?

A long-running mutating tool with 6 parameters, 17% schema coverage, no annotations, and no output schema. The description omits overwrite semantics and the role of the four required IDs, so it is not sufficient for an agent to invoke it 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 only 17% (just 'directory'), and the description says nothing about any of the 6 parameters. The 4 required IDs (id, messageID, providerID, modelID) are completely unexplained in both prose and schema, leaving the agent to guess their meaning.

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 pair (analyze, create) and a concrete artifact (AGENTS.md), which separates it from generic session tools like opencode_session_create. However, it does not distinguish itself from the closely-named sibling opencode_project_init, which by title sounds like it does the same thing.

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 on when to run this versus opencode_project_init or opencode_session_create, and no prerequisites (e.g., whether a session must exist first). The 60+ sibling list gives an agent plenty of reasons to need routing help that this description does not provide.

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 no annotations provided, the description carries the full behavioral burden, and it discloses almost nothing: no statement that this is a read-only operation, no pagination or result-limit behavior, and no indication of what a session record contains. 'List all sessions' leaves the agent to infer the safety profile and result shape.

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 short, front-loaded sentence with zero waste. It is efficient, though arguably under-specified rather than genuinely concise given what a session-list tool needs to convey.

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 listing tool with no output schema, the description should at minimum indicate the scope of returned data or pagination behavior. Instead it is a bare four-word sentence, leaving return format and result limits entirely undocumented.

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 and its default behavior are already fully documented in the schema. The description adds no syntax, format, or semantics beyond that, so the baseline 3 applies; if anything, 'all sessions' slightly obscures the existence of the filter.

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 clear verb and resource ('List all sessions'), so the basic action is unambiguous. However, it does nothing to distinguish this tool from siblings like opencode_session_search, opencode_session_get, or opencode_sessions_overview, and the word 'all' is arguably misleading given the schema's optional directory scoping filter.

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 the many adjacent session/overview/search tools. No prerequisites, no mention of how it relates to opencode_sessions_overview, which sounds functionally overlapping.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it never explains what each reply actually does (grant once? persist a standing approval? deny and what happens next?). For a decision tool whose 'always' option likely has lasting security consequences, this omission is significant.

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 terse sentence with the action front-loaded and no filler. It is efficiently sized, though the extreme brevity is more a symptom of under-specification than of disciplined conciseness.

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 mutation/decision tool with no annotations, no output schema, and an undocumented required parameter, the description is too thin. An agent cannot tell what happens after a reply, whether 'always' is durable, or how the request ID was obtained.

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 only 50%, and the required permissionID parameter has no description in either the schema or the description. The description merely restates the reply enum values that the schema already enumerates, adding no meaning about id, permissionID, or how replies are scoped.

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+resource: 'Respond to a permission request,' and enumerates the valid replies. It implicitly distinguishes itself from read-only siblings like opencode_permission_list, but never names that sibling or explains how a pending request is discovered, so differentiation is only partial.