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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the schema enumerates the confirm/force guards and the 'refuses while opencode serve is running' rule. The description adds only the phrases 'rotation + disk guard', which hint at retention and free-space checks without explaining either. Nothing contradicts the annotations, but little is added beyond them.

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

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

The purpose sentence is front-loaded and tight. However, the '## Return Format' block restates a return shape that the output schema already defines, and the examples duplicate enum values already in the schema, so a portion of the text does not earn 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?

An output schema exists, so the description needn't explain return values (and its return-format block is therefore redundant). It also leaves the destructive restore/delete paths to the schema rather than warning about overwriting live data in prose. Adequate, but with avoidable gaps for a destructive 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%, including detailed per-action semantics and confirm/force rules, so the baseline is 3. The description's examples illustrate action/kind/name/confirm combinations but add no syntax or constraint information the schema lacks.

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 opening sentence names a specific resource (opencode database and config) and the two primary verbs (backup, restore), plus differentiating traits (rotation, disk guard). It doesn't cover the other four actions (status, list, prune, delete), which are only discoverable from the schema enum. No sibling does backups, so differentiation is not a concern.

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?

'restore when needed' is the only usage hint and it is essentially tautological. The examples show call shapes for status/create/list/restore but give no conditions for choosing prune over delete, or when to check status first. Usage is implied by the action examples rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds a return format and example, but does not explain irreversibility, permissions, or what happens if the run is already completed or missing.

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

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

The description is short and front-loaded with the action. The return format and example are compact and do not add unnecessary prose.

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 destructive cancel tool, the description covers the action, return shape, and an example. It could be more complete by noting failure conditions or what happens when a run cannot be cancelled, but the core invocation context is present.

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 job_id parameter is fully documented in the schema. The example shows an identifier format, but the description adds no semantic 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?

The description states a specific verb and resource: cancel an agent run, scoped to running or queued runs. It is clear what the tool does, though it does not explicitly differentiate itself from sibling status/list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'running or queued agent run' implies when cancellation is applicable, but there is no explicit guidance on when not to use it or which sibling to use to inspect run status 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?

The description discloses exactly what the coarse destructiveHint=true annotation cannot: archive/unarchive/rename are reversible, delete is permanent with FK cascade into messages, star writes to a sidecar db and never touches opencode.db. It also notes the tool reads SQLite directly and works without `opencode serve`, and names the rag/code dependency and index requirement. That is meaningful per-action behavioral nuance layered on top of the annotations rather than repetition.

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 opening sentence front-loads purpose and the reversibility line is placed immediately after, so the highest-value information is early. The mechanism/rag-code paragraph and return-format block are tight. The 14-line examples block is somewhat heavy for the space available and partly duplicates the action enum's own descriptions, but it does earn its place for a 21-action tool by showing valid combinations.

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 21-action, 21-param tool this description covers purpose, action semantics, reversibility/destructiveness, prerequisites and return shape, and an output schema already exists so return values need not be detailed. It leaves some per-action return differences and edge cases (e.g. export out_path defaults, code_index rebuild scope) to the schema, which is acceptable but not fully rounded out.

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 already 100%, including a long per-action description in the action enum, so the baseline is 3. The description adds value by grouping which filters apply to which action (e.g. 'search filters: query + optional timeframe_days, project, include_archived, starred, tag') and by flagging comma-separated tag syntax, plus examples that show valid parameter pairings. It does not fully document date_from/date_to precedence or offset behavior 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?

The first sentence states a concrete resource (opencode's SQLite session depot) and enumerates the operations it exposes: list, inspect, archive, rename, delete, search, rag, code, stats. It also distinguishes search (exact/full-text) from rag (semantic) and code (file-touch recall), which an agent cannot infer from the names alone. It stops short of naming overlapping siblings such as opencode_list_sessions or opencode_get_session, so sibling differentiation is incomplete.

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 gives real when-to-use guidance: 'search = exact/full-text wayback find; rag = semantic similarity; code = when an agent touched a file', and states the prerequisite that rag/code need `uv sync --extra rag` plus an index pass. The 14 examples demonstrate action/param combinations concretely. It never says when to use this instead of the sibling session tools (opencode_list_sessions, opencode_get_session), so there are no explicit alternatives/exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the return shape and warns implicitly that the payload includes bulk content (instructions), but says nothing about size, sensitivity of config values, or failure modes.

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

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

Front-loaded one-line purpose followed by return format, with no filler prose. The '## Examples' block showing `opencode_get_config()` adds nothing for a zero-arg tool and could be dropped.

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 exists, but the description compensates with an explicit return format ({success, message, data.config}). For a parameterless read, that is nearly everything an agent needs, short of noting that config may contain secrets or be large.

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?

Zero-parameter tool, so the baseline is 4; the empty schema with additionalProperties false leaves nothing for the description to explain.

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 ('Read the full opencode configuration') and enumerates what it contains (model, provider, MCP server settings, instructions), which clearly separates it from session/run siblings. It does not explicitly name which sibling to use instead for narrower reads like providers or project.

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_list_providers, opencode_get_project, or opencode_system, nor any preconditions. Usage is only inferable from the tool name and the word 'full'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context in the return format and the fact that uptime is reported, but says nothing about timeouts, failure modes, or latency — modest added value on top of annotations.

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

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

Front-loaded with the purpose, then return format and example. The '## Examples' block for a zero-argument call is largely ceremonial and doesn't earn its space, but the rest is tight.

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 inline Return Format ({success, message, data}) usefully covers the return shape, and a zero-parameter health check needs little else. Lacking only explicit guidance on when to prefer it over its status-oriented 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The explicit empty example opencode_get_health() confirms no arguments are needed.

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 (health check for the opencode server) plus what is returned (connectivity status and uptime). It's clear what the tool does, though it doesn't distinguish itself from the sibling opencode_server_status, which plausibly overlaps.

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 name and the word 'health check', but the description never states when to call this versus opencode_server_status or opencode_system, nor any prerequisites. Adequate but with a clear routing gap.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely new context by disclosing the response envelope shape, which matters because no output schema exists. It stops short of explaining ordering, pagination, or what happens when limit truncates history.

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?

Purpose is front-loaded in the first sentence, followed by return format and a single example — a sensible order with little waste. The return-format block is abbreviated ('{"role": str}' only) and slightly padded relative to its information 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 two-parameter read-only tool with full schema coverage and annotations, the description covers purpose, response envelope, and a usage example. Remaining gaps — message ordering and truncation semantics for limit — are modest but real for an agent interpreting the transcript.

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 both parameters are documented in the schema, so the baseline is 3. The example adds a concrete session_id format hint ('sess_01'), but no additional semantics for limit behavior (e.g., newest-first truncation) are supplied.

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 ('Retrieve message history from an opencode session') and clarifies the payload ('conversation transcript between the user and the agent'). It does not explicitly contrast with siblings like opencode_get_session or opencode_send_message, so an agent must infer the boundary itself.

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 by the phrase 'retrieve message history'; there is no statement of when to prefer this over opencode_get_session, opencode_list_sessions, or opencode_session_diff. The example shows a plausible call but not a decision rule.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety and repeatability are covered. The description adds the return shape ({success, message, data.project}), which is genuinely useful context beyond the annotations. It does not cover failure behavior or what happens when no project is active.

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?

Front-loaded with the purpose, followed by the return format. The Examples section containing just 'opencode_get_project()' adds nothing for a zero-arg tool and is the only wasted line.

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 carries the burden of describing the response, and it does so with the exact return shape. The main missing piece is the no-active-project / failure case, which matters for a context-discovery 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool is 4.

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 ('Get the current project context') and narrows to 'active project path and metadata', which separates it from sibling getters like opencode_get_config and opencode_get_health. It does not explicitly name those siblings as alternatives, but the resource is distinct enough to be 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 statement of when to call this versus opencode_get_config, opencode_system, or opencode_get_session, and no prerequisites or exclusions. The only hint of usage is that it returns 'the active project', which an agent must infer.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context by explaining that it returns stdout/stderr accumulated so far, status, and exit code, plus the exact return shape. It does not mention polling cadence or rate limits, but the annotations lower the disclosure burden.

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 front-loaded with purpose, followed by return format and a concise example. Every sentence contributes useful information without unnecessary repetition or filler.

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

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

There is no output schema, but the description compensates by providing the exact return format, including the structure of the data object. It is nearly complete for a polling tool, though it could optionally mention possible status values or what happens after the job completes.

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 schema already documents that job_id is a string 'Job ID from opencode_run_agent'. The description includes an example call but does not add meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Poll the status of a background agent run.' It clearly distinguishes the tool from siblings such as opencode_run_agent, opencode_cancel_run, and opencode_list_runs by focusing on status polling for a single background job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by saying 'Poll' and identifying the job_id as coming from opencode_run_agent, but it does not explicitly state when to use this tool versus opencode_list_runs or opencode_get_health, nor does it provide exclusions or alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds a return-format sketch and an example call, which is useful since there is no output schema, but 'data': {'session': dict} is unspecified — a caller still doesn't know what fields 'metadata and state' actually contain.

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?

Front-loaded one-line purpose followed by structured Return Format and Examples sections; short and scannable. The 'dict' placeholder in the return format is the only sentence that earns little.

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 single-param read tool this is nearly adequate, but with no output schema the return description must carry the load, and 'session': dict leaves the shape of metadata/state opaque. It also doesn't relate the tool to nearby siblings like opencode_get_messages or opencode_session_diff that an agent might want 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 description coverage is 100% and the single session_id parameter is documented in the schema ('Session ID to retrieve'). The description's example shows the parameter name and a sample value format ('sess_01'), which is marginally additive but does not explain the ID source or format beyond the example.

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 ('detailed information about a specific opencode session') and clarifies it returns metadata and state. This clearly distinguishes it from list-style siblings like opencode_list_sessions, 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?

Usage is only implied: the required session_id and the word 'specific' suggest fetching one known session rather than enumerating. There is no explicit when-to-use statement, no exclusion, and no mention of opencode_list_sessions or opencode_get_messages as 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?

Only readOnlyHint=false is declared, so the description must carry behavioral weight. It usefully documents the return payload and the three modes, but omits key traits: whether the call blocks until the UI exits, what happens if a UI/server is already running, and what the 'serve' background mode implies for later shutdown (a sibling opencode_shutdown exists but isn't referenced).

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?

Front-loaded purpose sentence, then compact Return Format and Examples sections. Slightly more scaffolding than a 2-parameter tool strictly needs, but nothing is wasted or buried.

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 exists, so the explicit Return Format block is valuable and covers the return contract. The remaining gap is lifecycle behavior (blocking, re-launch, pairing with opencode_shutdown), which matters for a tool that starts long-lived processes.

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% with an enum on mode and a documented default, so the schema already does the heavy lifting. The two examples (mode="web", mode="serve") show call shape but add no semantic detail beyond the enum descriptions, 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 (launch) and resource (opencode interface) plus three distinct modes (TUI, web UI, background API server). It is clearly distinct from the sibling tools, which manage sessions/runs/config, though it doesn't explicitly name a sibling to contrast against.

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?

'Use this to open the opencode interface for manual work' implies the context (interactive/manual use vs. the programmatic run/agent tools), but there is no explicit when-not guidance, no mention of conflicts with running instances, and no named alternative to route to instead.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered; the description adds real value beyond that by disclosing the exact return envelope (success/message/data.providers[].name), which matters because no output schema exists. It stops short of covering failure modes (e.g. what happens when no providers are configured) or whether credentials/validation are involved.

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?

Front-loaded one-line purpose followed by a compact return schema; nothing is bloated. The '## Examples' section restates the zero-argument call with no added information, which is the only near-dead weight.

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 zero-parameter, read-only listing tool with no output schema, the description supplies enough: purpose, return shape, and a call example. A brief note on what 'configured' means (e.g. whether unconfigured/available providers are excluded) would close the remaining gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The example call correctly reinforces the no-argument invocation.

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 configured LLM providers in opencode'), which is unambiguous. It is implicitly distinguishable from siblings like opencode_get_config or opencode_get_health, but it never names or contrasts those alternatives 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?

Usage is only implied by the tool's name and zero-parameter signature — an agent will infer 'call this to discover available providers.' There is no statement of when to prefer it over opencode_get_config (which likely also exposes provider configuration) and no exclusions 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered structurally. The description adds the return shape (job_id, status, exit_code), but leaves ambiguous what 'recent' means, how runs are ordered, or whether results are paginated beyond the limit cap.

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?

Purpose is front-loaded in a single sentence, followed by a compact return-format block and one example line. Nothing is repetitive, though the example adds little given a single bounded integer parameter.

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 usefully supplies the exact return envelope, which is the main gap it needed to cover. It is slightly incomplete on ordering and the meaning of 'recent', but an agent can call it correctly from what is given.

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 limit parameter already documents its type, default of 20, and 1-100 bounds. The description only repeats the parameter in an example call, adding no semantics such as ordering or what happens when limit exceeds available runs.

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 and resource: 'List all recent agent runs with their status and exit codes' tells the agent exactly what is returned. It does not explicitly contrast itself with near-siblings like opencode_get_run_status (single run) or opencode_runs, so differentiation is left implicit.

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_get_run_status or opencode_runs, and no prerequisites or exclusions. The only usage signal is an example call with limit=20, which demonstrates syntax rather than selection 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?

Annotations already declare readOnlyHint and idempotentHint, so safety behavior is covered. The description adds a return format and an example, which is useful given there is no output schema, but it does not disclose auth requirements, rate limits, or what 'recent' means operationally.

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?

Purpose is front-loaded and the return format is compact. The example 'opencode_list_sessions()' adds little for a zero-argument tool, but overall length is appropriate.

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 zero-parameter, read-only listing tool with annotations and no output schema, the description supplies the missing return shape. The main remaining gap is sibling differentiation from opencode_sessions.

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 tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly avoids burdening the reader with nonexistent parameter details.

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 the specific verb 'List' and resource 'opencode sessions' and adds the scope 'active and recent'. This helps distinguish it from a single-session getter, though it does not explicitly differentiate from the sibling opencode_sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no explicit when-to-use guidance, no exclusions, and does not name alternatives such as opencode_sessions or opencode_get_session. The agent must infer selection from the purpose line 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 only `readOnlyHint: false` in annotations, the description carries most of the behavioral burden and does well: it explains that the tool unpacks/reads a bundle, extracts a manifest, and merges a server definition into the config file. It does not explicitly describe overwrite/conflict behavior for existing server entries, but the mutation and `dry_run` semantics are sufficiently clear.

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 front-loaded with purpose and workflow, then provides return format and examples. It is generally well-structured and efficient, though the return format section is partly redundant because an output schema exists.

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

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

Given the tool has an output schema, full parameter description coverage, and a clear mutation annotation, the description is nearly complete. It explains the mutation workflow and return shape; the main remaining gap is not explaining how existing server name conflicts are handled.

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 schema already documents `source`, `dry_run`, and `name_override` meaningfully. The description's examples demonstrate usage scenarios but do not add significant parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: installing an MCPB bundle into opencode config. It also explains the core workflow—unpacking the bundle or reading a directory, extracting the manifest, and merging the server definition into the config's `mcp` section—so an agent can understand exactly what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly establishes the context: use this when installing an MCPB bundle or unpacked MCPB directory into opencode config. The examples reinforce usage, but there are no explicit exclusions or alternative tools for other installation paths.

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

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

The only annotation is readOnlyHint=false, so the description must carry the behavioral load and it does: asynchronous background execution, job_id polling contract, wait/timeout interaction, and the specific unattended-run stall risk from permission prompts. It also spells out the return envelope (success/message/data.job_id/status/options), which the annotations do not cover at all.

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?

Front-loaded correctly: purpose and launch semantics come first, then the unattended-run caveat, then a clearly headed Return Format block, then examples. Each of the four examples demonstrates a distinct parameter combination rather than repeating the same call, so the length is justified. It is still a fairly long block for a tool whose core contract fits in two sentences.

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 14-parameter mutation tool with no output schema, the description supplies the missing return shape, the async lifecycle entry point, and the timeout/permission pitfall that would otherwise cause silent failures. An agent can construct a correct call and know how to follow up on the job_id from the description alone; remaining gaps (status vocabulary, cancellation via opencode_cancel_run) are minor and covered by 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 100%, so a 3 is the baseline and the schema already explains each of the 14 parameters. The description adds compositional meaning the schema cannot convey: the wait/timeout pairing, auto=true as the fix for unattended stalls, and worked examples showing session_id+fork and model+agent+auto together. It does not clarify the relationship between continue_session and fork or what status values appear in data.status.

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 first line names a specific verb and resource ('Run an opencode agent') plus the key knobs (prompt, model, agent, permission mode), and the second line clarifies that it launches a background job returning a job_id. This implicitly separates it from the polling siblings (opencode_get_run_status, opencode_list_runs), but no sibling is ever named, so the differentiation is inferential 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?

It gives concrete conditional guidance: set wait=true to block, unattended runs usually need auto=true or a permission prompt will stall the run until timeout. That is real when-to-use advice tied to failure modes. It stops short of a 5 because it never says when to prefer opencode_send_message (continue an existing session) or opencode_launch_ui over starting a new agent run, even though session_id/continue_session/fork make that choice relevant.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds useful async semantics (fire-and-forget returns job_id, poll to retrieve results) and a return-shape hint, but it never mentions that cancel terminates a running agent or what auto/timeout imply behaviorally beyond the schema text.

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 purpose line is front-loaded and the return-format block is compact. Five examples is on the generous side for an 18-parameter tool, but each demonstrates a distinct action or flag combination, so they largely earn their 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?

An output schema exists, making the explicit return-format block somewhat redundant, and the async polling note plus examples cover the main calling patterns. The only real gap is the absence of any guidance distinguishing this tool from the single-action siblings that cover the same ground.

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 baseline is 3 regardless of description content. The examples do add value by showing which parameters pair with which action (model/agent/auto with start, job_id with status, limit/offset with list), but no format or constraint 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?

The description states specific verbs and the resource: 'start, poll status, list recent, or cancel' agent runs, and the action enum is labeled accordingly. It does not, however, distinguish this tool from direct siblings that appear to do the same individual jobs (opencode_run_agent, opencode_get_run_status, opencode_list_runs, opencode_cancel_run), so an agent has no signal for when to pick this multi-action tool over the narrow ones.

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?

Workflow guidance is implied through the note that fire-and-forget starts return a job_id which you poll with action="status", and the examples demonstrate realistic call shapes. There is no explicit when-to-use/when-not statement and no mention of the sibling alternatives, leaving the routing decision 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?

The annotation only declares readOnlyHint=false; the description usefully adds the return envelope {"success", "message", "data": {"result"}} since there is no output schema. It does not disclose whether the call blocks until the agent replies, what happens on an invalid or busy session, or whether delivery is queued or immediate.

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?

Front-loaded two-sentence purpose followed by clearly labeled Return Format and Example sections; nothing is buried. The example largely restates the schema, which costs a little, but overall the text is tight.

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 2-required-parameter mutation tool with no output schema, supplying the return envelope is the key missing piece and it is present. The remaining gap is the lack of any error/edge-case behavior, which matters because sending to a nonexistent session is a realistic failure mode.

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

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

Schema description coverage is 100%, so both parameters are already documented in-schema and the baseline is 3. The example adds a concrete shape (session_id="sess_01", message="continue") that hints at sending a short continuation prompt, but adds no real semantic depth 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+resource (send a message to an existing session) and adds the intent (continue a conversation with a running agent). It implicitly separates itself from opencode_run_agent and the read-side opencode_get_messages, 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?

'Use this to continue a conversation with a running agent' plus 'existing session' establishes the precondition that a session must already exist, which is useful. However, it names no alternatives (e.g. run_agent for new work, get_messages for reading) and gives no guidance for a missing, idle, or terminated session.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the shape of the response and the categories of data returned, but says nothing about cost, latency, auth prerequisites, or whether it fails when the server is down — notable gaps for a health-check 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 purpose is front-loaded in the first line and the return format is clearly sectioned. The '## Examples' block containing a bare no-argument call adds nothing an agent couldn't infer, which is the only wasted 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?

No output schema exists, but the description compensates by documenting the return envelope and the data categories. What's missing is failure-mode behavior (what happens when the server is unreachable), which matters for a status/health 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?

There are zero parameters and the schema disallows additional properties, so there is nothing for the description to disambiguate. Baseline 4 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: 'Check the status and health of the opencode server', with a summary of what comes back (health info, active session count, config summary). It does not distinguish itself from close siblings such as opencode_get_health or opencode_system, 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?

Usage is only implied — an agent must infer from the returned fields (health, sessions, config) that this is a general-purpose overview. There is no explicit when-to-use/when-not guidance and no mention of the obvious alternatives opencode_get_health or opencode_system.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds real value beyond that by specifying the return format and stating the diff includes file paths and change types, giving the agent a sense of output shape for a tool with no output schema.

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

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

The core purpose is front-loaded in the first sentence, followed by output shape and a compact example. Slightly more scaffolding (labeled sections) than strictly needed for a one-parameter tool, but nothing is 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?

With no output schema, the description appropriately explains the return structure and diff contents, which is exactly what an agent needs to interpret results. Only usage/differentiation guidance is missing, so it is nearly complete for a simple read 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 100% for the single session_id parameter, so the schema already documents it. The description's example (session_id="sess_01") adds only superficial format illustration, 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 (show) and resource (files created/modified/deleted in a session), which is concrete and distinguishable from a generic session fetch. It does not, however, explicitly contrast itself with close siblings like opencode_get_session or opencode_get_messages.

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 – diff a session's file changes – but there is no explicit when-to-use/when-not or naming of alternatives such as opencode_get_session for metadata vs. this for file diffs. The example clarifies the call shape but not the routing 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?

Annotations only give readOnlyHint=false, so the description must carry the safety burden and it largely does: delete is flagged as permanent and gated on confirm=True, share is described as 'offline, revocable', unshare as revocation, and rename as affecting the serve API and live UI. What is missing is the auth/permission requirements and any note that this tool mixes read and write actions in one surface.

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 opening sentence simply re-lists the enum values already present in the schema, which is wasted text, and the 'Return Format' line duplicates a return value the tool already declares via output schema. The Examples block does earn its place, and the structure is front-loaded, but roughly a third of the description is redundant with structured 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 nine-parameter, eleven-action tool with a full output schema, the description covers action scope and mutation behavior adequately. The gaps are the absence of any sibling routing guidance (critical given five near-duplicate siblings) and no error or failure-mode information for actions like send/grep on nonexistent sessions.

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 baseline is 3; the description earns a bump because the Examples block ties parameters to specific actions (session_id with get/messages/send/diff/export/share/unshare/rename/delete, query with grep, format with export), which the flat schema does not express. It still doesn't clarify pagination semantics for offset/limit across list vs messages.

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 ('Inspect and interact with') plus resource ('opencode sessions') and enumerates the twelve operations in scope, so an agent knows exactly what the tool covers. However, it never distinguishes itself from highly overlapping siblings such as opencode_list_sessions, opencode_get_session, opencode_send_message, opencode_get_messages, and opencode_session_diff, which is the main purpose-clarity gap for a facade tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Examples block implicitly demonstrates which action pairs with which parameters (action='messages' with session_id, action='rename' with title, action='delete' with confirm=True), which is real invocation guidance. But there is no explicit when-to-use-this-vs-alternative guidance, and nothing tells the agent why it should call this consolidated tool rather than the granular session 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?

The annotations already flag destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. The description adds that shutdown is graceful and that the optional reason is written to stderr, but it does not disclose the impact on active runs, sessions, or whether shutdown is irreversible.

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

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

The description is short and front-loads the purpose before return format and examples. The return format section duplicates the existing output schema, but it is brief and does not significantly harm readability.

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

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

The tool is low-complexity, has full schema descriptions, annotations, and an output schema, and the description provides enough to identify and invoke it. The main missing context is the operational impact of a destructive shutdown, which is only partially covered by the destructive annotation.

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

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

Schema description coverage is 100%, so the schema already explains both parameters. The examples add invocation shape, but the confirm=False example is ambiguous because the schema says confirm must be True to shut down, and the description does not explain what that example would accomplish.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Shut down this MCP server process gracefully.' It is unambiguous and clearly distinct from sibling tools such as opencode_server_status, opencode_get_health, and opencode_cancel_run.

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 examples imply the tool is used with confirm=True, but the description never explicitly states when to use this tool, when not to use it, or what confirm=False actually does. Usage is inferable from the name but not fully guided.

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

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

Annotations declare readOnlyHint=false, and the description correctly implies most actions are reads while one (launch_ui) mutates – no contradiction. However, it never says which of the six actions are side-effecting, nor what launch_ui actually does (spin up a long-running process? return immediately?), which is the main behavior risk an agent needs to know. The return-format block adds a little context, though it duplicates the output schema.

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

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

Sized appropriately and the examples are genuinely useful for call shape, but the opening fragment is under-specified rather than concise, and the Return Format block restates an output schema that already exists – a sentence that does not earn its place.

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

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

For a six-action multiplexer with a non-read-only annotation, the description should tell the agent which actions are safe probes versus which launch processes, and how this tool relates to its many single-purpose siblings. It instead provides a return-format restatement and three examples, leaving the routing and side-effect questions unanswered.

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 action enum already documents each value ('status: health + startup probe...', 'config_drift: check local MCP server paths exist on disk'), so the parameter work is done. The description's examples show realistic action/mode pairings (action="launch_ui", mode="web") but add no semantic 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?

The first line is a noun-phrase fragment ('opencode server environment: health/status, providers, project, launch UI, MCP pulse, or config drift') that enumerates the six actions but never states what the tool does with them as a whole. It is distinguishable from individual siblings only obliquely – opencode_server_status, opencode_list_providers, opencode_get_project and opencode_launch_ui all appear in the sibling list with overlapping scope, and the description never explains the difference between this multiplexer and those single-purpose tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance at all. Several siblings (opencode_server_status, opencode_list_providers, opencode_get_project, opencode_launch_ui) cover the same ground as individual actions here, and the description gives no rule for choosing between the multiplexed action and the dedicated sibling.

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 burden but does well by disclosing the rich Prefab card format, status badges, and the plain-text fallback return format. It does not mention any side effects or auth, but for a read-only display tool this is sufficient.

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 brief and well-organized: first sentence states purpose, second provides an alternative, and a 'Return Format' section clarifies output. Every sentence adds value without redundancy.

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

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

The description is largely complete for a simple tool: it gives purpose, alternative, and return format. The only gap is the unmentioned 'limit' parameter, which is a minor omission given the tool's simplicity and the parameter's self-descriptive name.

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 one param 'limit' with a default but no description, and the description does not mention it. Schema description coverage is 0%, so the description fails to compensate. The parameter name is somewhat intuitive, but the agent is left guessing about its exact semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Show recent agent runs as a rich Prefab card' with a specific verb, resource, and output format, effectively distinguishing it from the sibling opencode_runs tool. It also explicitly names the alternative for raw data, reinforcing its unique purpose.

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 explicit guidance: 'Use the plain opencode_runs(action="list") tool when you need raw data instead.' This clearly states when to use this tool versus the alternative, covering the primary decision point.

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 disclose behavioral traits itself. It mentions the return format ('ToolResult with PrefabApp card and plain-text fallback') and implies read-only behavior via 'Show' and 'Lists,' but does not explicitly state read-only status, permissions, or edge-case behavior. This is minimally adequate but not comprehensive.

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

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

The description is short and front-loaded with the core purpose, followed by a clear alternative and return format. It includes only necessary information with no redundancy, achieving high impact in few 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?

For a simple tool with one optional parameter, the description covers purpose, return format, and an alternative, but omits any explanation of the 'limit' parameter. Since there is no output schema, the return format mention is helpful, but the missing parameter semantics leave the description incomplete for full agent decision-making.

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 one parameter, 'limit,' with zero description, and schema description coverage is 0%. The description does not mention 'limit' at all, leaving its purpose, constraints, and optionality entirely up to inference from the name and default value. The description fails to compensate for the lack of schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Show opencode sessions as a rich Prefab card' and 'Lists recent opencode sessions,' clearly identifying the verb and resource. It also distinguishes from the sibling tool opencode_sessions by directing users to that tool for raw data, eliminating ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names an alternative: 'Use opencode_sessions(action="list") for raw data instead,' which helps an agent decide between presentation and raw data access. However, it does not provide broader guidance for when to use this vs other session-related siblings like opencode_list_sessions, so it's not a full when/when-not set.

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 and discloses the return format (ToolResult with PrefabApp card and plain-text fallback), which is valuable behavioral context. It does not describe error handling or side effects, but for a read-only status tool the fallback behavior is a meaningful disclosure.

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

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

The description is concise and front-loaded, with a clear main sentence, an alternative usage note, and a structured return format section. Every sentence adds value without redundancy, and the length is appropriate for the tool's simplicity.

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 zero-parameter status tool, the description covers the main purpose, displayed content, alternative raw-data tool, and return format. It could optionally mention it is read-only or contrast with the sibling opencode_server_status, but overall it provides sufficient information for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters, so the schema requires no documentation. The baseline of 4 applies because no parameter descriptions are needed, and the description does not need to explain any input semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Show') and resource ('opencode server status as a rich Prefab card'), and lists the exact content displayed (reachability, startup probe result, job counts). It distinguishes itself from raw data tools by explicitly naming opencode_system as an 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?

The description explicitly advises using opencode_system(action="status") for raw data, which clarifies when not to use this tool. It does not provide extended scenario guidance, but the alternative is clearly stated and the context implies this tool is for rich UI presentation.

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