opencode-workbench

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

Goes well beyond the annotations by disclosing the exact files overwritten (opencode.json, AGENTS.md), the repo reset to origin/main, global installs requiring write permission and SSH for mode:ssh, multi-minute duration, and the names-only mode-600 ~/.env.workbench write with no secret values. This is rich behavioral context consistent with destructiveHint=true and idempotentHint=true.

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?

Dense but front-loaded, leading with the destructive writes before the softer parameter notes. Every sentence carries new information; slightly long as a single block, but nothing is redundant with the schema.

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 destructive, multi-step, consent-gated tool with an output schema, the description covers the side effects, permission/time requirements, and parameter defaults an agent needs to invoke it safely. Return-value explanation is correctly omitted since an output schema exists.

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% (baseline 3), but the description adds real meaning: it documents defaults not fully stated in the schema (workspace defaults to ~/opencode-workbench), clarifies skipRepo/profileUrl/dryRun behavior, and ties mode:ssh to SSH auth requirements.

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

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

States a specific verb and resource ('Apply the Workbench profile', clone repo, install missing components) and enumerates the exact artifacts touched. It clearly distinguishes itself from the sibling plan_clone by naming it as the preview-only 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?

Explicitly tells the agent when to use it and when not: consent-gated (needs confirm:true, otherwise returns a plan and changes nothing) and 'To preview only, use plan_clone.' Named alternative plus the condition that selects it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; 'always safe' and 'takes no parameters' largely restate them. The description does add useful context beyond annotations — that it reads a bundled profile without contacting any target or making a network call and returns instantly — but does not describe return format details (left to 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?

Front-loaded with the core purpose and return contents, followed by usage and alternative routing. Efficient overall, though the 'takes no parameters, is always safe, and returns instantly' clause is somewhat redundant with the annotations.

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 tool, the description covers purpose, usage, alternatives, and key behavioral traits. Since an output schema exists, enumerating return values is extra rather than necessary, but nothing an agent needs in order to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description confirms it takes no parameters, which is accurate but adds no parameter-level meaning since there is nothing to document.

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 (describe) and resource (this MCP server from its bundled profile), then enumerates exactly what it returns: repository URL, default component set, components grouped by tier, and optional MCP add-ons. It also distinguishes itself from inspect_target by scope (bundled profile vs. machine's live 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?

Explicitly says to use it first to resolve a component id for install_component/remove_component/update_component or to view add-ons, and names the alternative inspect_target for a machine's live state. Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing the exact execution model (one shell probe as the target user, over SSH in ssh mode), the side-effect profile (installs nothing, writes nothing, no external service), latency (a few seconds per hop), and a privacy guarantee (credential names, never values).

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 purpose before behavior, usage, and parameters, and every sentence carries information. It is a dense single paragraph that could be broken up, but there is little redundancy to cut.

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

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

An output schema exists so return values need not be re-explained, and the description still covers scope, side effects, latency, parameter behavior, and the follow-on workflow. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description still adds value by explaining mode default, that host is required only for ssh, and that port/identityFile pass straight through to ssh. Minor nit: it calls mode default `local` while the schema marks it required, a small inconsistency rather than a contradiction.

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 ('probe one Linux machine') and enumerates exactly what is reported (OS, kernel, architecture, package manager, Node/npm, OpenCode, Docker, detection flags, credential names). This is clearly distinguishable from siblings like describe_workbench or verify_clone.

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

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

Explicitly routes the agent: use inspect_target to see what a clone would touch, then plan_clone for an ordered plan, then apply_clone to perform it. The when-to-use and the named alternatives are both present, leaving nothing 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?

Goes well beyond the destructiveHint/idempotentHint annotations: it names exactly what gets overwritten (skills/plugins replacing copies under <home>/.config/opencode), that global installs require write permission and can take minutes, and that without confirm:true it returns a plan and makes no changes. The overwrite disclosure is consistent with destructiveHint=true.

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 core action, then packs overwrite/timing/consent details into dense clauses. Every sentence carries information, though the single long middle sentence is heavily parenthetical and slightly harder to parse than necessary.

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 consent-gated, destructive, environment-dependent install tool with a nested target object, the description covers side effects, permission needs, latency, default plan-only behavior, and sibling routing. With an output schema present, return values need not be restated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema omits: default values for `workspace` (~/opencode-workbench) and `confirm` (false, plan only), and confirms `component` is required. It does not explain the nested `target` object's ssh fields, which the schema already covers.

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?

Opens with a specific verb+resource+topic: 'Install a single Workbench component by id', and enumerates example ids. It also implicitly distinguishes itself from remove_component/update_component by scoping to installation of one component.

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

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

Explicitly routes the agent: 'Use it for one targeted component; use apply_clone to install the full default set.' It also states the prerequisite that `component` must be an id from describe_workbench, giving both when-to-use and where-to-get-inputs 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 declare readOnlyHint and idempotentHint, but the description adds materially more: 'value-blind', reads only whether each env var is set, 'no values, no network, no writes', via a single read-only probe. These are real behavioral guarantees beyond the annotation set, so the agent knows the blast radius and data exposure precisely.

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?

Dense but front-loaded: purpose, then safety profile, then parameter semantics, then return shape, then usage. Every clause carries information, though the parameter and return sentences are packed tightly enough that it reads more like a spec block than 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?

Even though an output schema exists, the description still sketches the return shape (`present`/`missing` arrays plus per-credential `var`, `purpose`, `url`, `method`, `command`), which makes the tool self-sufficient for an agent deciding whether to call it. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns an extra point by explaining the consequence of `target`: it selects the machine (local or SSH) and drives the returned `template` path and the env file the presence check reads. Minor gap: it references a `home` field that is not present in the schema's target object, which could momentarily confuse an agent about the shape of the 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?

Opens with a specific verb+resource (list the credentials the profile references) and immediately distinguishes three output categories: already-provided, referenced, and how to acquire missing ones. An agent can tell exactly what this returns without opening the schema, and it reads distinctly from siblings like run_auth_flow or plan_clone.

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

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

Explicitly states the sequencing ('Use it after plan_clone to see what would degrade') and names the correct follow-up action for a single credential ('act on one credential with run_auth_flow'). This is textbook when-to-use plus named alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, yet the description adds a genuinely useful nuance: it still runs a detection probe on the target (same access as inspect_target) but clones and writes nothing. That clarifies that 'read-only' still implies remote access, which the annotations alone don't convey. It stops short of describing return shape, though an output schema exists.

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

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

Front-loaded with the tool's output, followed by the behavioral caveat, parameter notes, and the sibling routing. Every sentence carries distinct information; nothing is redundant with the schema or annotations.

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

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

With an output schema present, return values need no explanation, and the description covers behavior, defaults and the apply_clone relationship. The one omission is that `dryRun` on an already read-only tool is unaddressed, leaving the agent to guess whether it is a no-op.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the `components` default (required+core), the `workspace` default path, and that `profileUrl` overrides the git remote. It does not explain `skipRepo` or `dryRun`, which is the only 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 ('Return a read-only plan') plus exactly what the plan contains: a per-component classification of install/present/manual with the commands that would run. This immediately separates it from siblings like inspect_target and apply_clone.

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

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

Explicitly names the alternative ('Use it to preview before apply_clone, which performs the changes') and gives the condition that selects it. It also disambiguates against inspect_target by noting the shared probe access, so the agent knows when each applies.

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?

Beyond the destructive/idempotent annotations it discloses consent gating (no `confirm:true` means preview only, nothing changes), idempotent outcomes (`absent` vs `manual` for non-automated system packages), and the exact deletion boundary (never `opencode.json` or the profile repo). This is precisely the extra context annotations cannot carry.

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?

Dense but well front-loaded: purpose, scope, then behavior, then parameter notes, then the multi-id routing rule. Length is justified by the tool's complexity, though `dryRun` and `confirm` are effectively restated from the schema, which is mild 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?

An output schema exists so return values need no explanation, yet the description still covers the enum-like outcomes an agent must interpret (`absent`, `manual`, preview). Nothing needed to call or interpret this destructive tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents target/confirm/dryRun/component/workspace, and the description largely restates them. It adds only a small increment (that `workspace` supplies the profile path needed by some removals). Baseline 3 applies 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 ('Uninstall one Workbench component by id from a target') and explicitly positions itself as the inverse of install_component, letting an agent separate it from siblings without opening any schema. It also bounds the scope to the documented subset with automated uninstall.

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?

Gives clear routing: 'Use it to tear down one component; for several, call it per id,' plus the precondition that the id comes from describe_workbench. It does not name when a different sibling (e.g. update_component) is the better choice, so it falls short of full when/when-not 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 declare readOnly/openWorld/idempotent, but the description adds substantial context beyond them: it is 'value-blind', 'does not run the commands or handle secret values', performs 'one read-only probe' to re-check presence, and errors on unknown names. This is exactly the extra behavioral disclosure the annotations cannot carry.

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 what the tool returns, then behavior, then parameter semantics, then scope. Dense but organized; a couple of clauses border on restating the sibling routing, keeping it just short of 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?

Even though an output schema exists (so return values need not be explained), the definition covers return shape, mutation-free behavior, parameter sourcing and constraints, and its relationship to list_required_credentials. Nothing an agent needs to select or call it is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by stating var must come from list_required_credentials and that unknown names error, plus that target selects the machine whose home is the write destination. Incremental value over the schema, but modest.

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 ('Return the acquisition plan for one credential on a target') and enumerates the payload (provider URL, exact non-interactive command, presence). It explicitly distinguishes itself from the sibling list_required_credentials ('Use it for a single credential; it does not replace that listing').

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?

Names the required upstream alternative ('var must be an env var name returned by list_required_credentials') and the scope condition that selects this tool (single credential, not the listing). Explicit when-to-use and a clear boundary against the 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?

Goes well beyond the destructiveHint/openWorldHint annotations: it discloses that files are OVERWRITTEN, that write permission is needed, that the operation can take minutes for global installs, that the resolved version may change, and that confirm defaults to false with a preview otherwise. These are exactly the operationally relevant facts an agent needs before invoking a destructive 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?

Purpose and mechanism are front-loaded, then risk (overwrite, permission, duration), then parameter semantics, then the sibling alternative. Dense but every clause carries information; nothing is redundant with the schema or annotations.

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 destructive, long-running, permission-gated mutation with an output schema and full parameter documentation, the description covers effect, preconditions, duration, defaults, and the alternative tool. An agent has everything needed to call it correctly without inferring anything.

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%, so the baseline is 3, but the description adds value the schema does not: it constrains `component` to an id from describe_workbench and supplies the actual default for `workspace` (`~/opencode-workbench`), which the schema leaves unspecified. It omits detail on the nested `target` object, but that is thoroughly documented in 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 and resource ('Update one Workbench component in place by id') and immediately explains the mechanism: re-running the component's install script to fetch the current version, with concrete examples (`opencode`, `npm-mcps`). This is unmistakably distinct from the sibling apply_clone, which it explicitly names as the whole-profile 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?

Clearly tells the agent how to actually apply the change ('set `confirm:true` to apply', `dryRun` previews) and routes the whole-profile case to apply_clone. It does not explicitly state when *not* to use this tool (e.g. use install_component for a component that isn't installed yet), so it stops short of full 5-level routing.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's 'read-only and idempotent, writing nothing' is partly redundant, but it adds genuinely new context: it names the mechanism (SSH or local detection probe, file checks) and what is checked. Output schema exists, so return format needn't be repeated. Solid added value beyond annotations.

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

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

Front-loads purpose and output, then behavior, then parameters, then usage routing. Dense but every clause earns its place; only the redundant read-only/idempotent clause overlaps annotations.

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 6-param tool with nested objects and an output schema, the description covers purpose, non-mutating behavior, parameter roles, and sibling routing. Minor gap: dryRun/skipRepo/profileUrl aren't addressed, though schema descriptions cover them.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond by explaining the role of target ('selects the machine and its home drives where the opencode.json and ~/.env.workbench checks run'), the component-restriction semantics of components, and the profile-path role of workspace. This clarifies how parameters interact, which the schema does not.

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

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

States a specific verb+resource ('Re-check a target after a clone') and enumerates the exact output ('per-component present/missing list plus whether opencode.json and ~/.env.workbench exist'). Clearly distinguishes itself from plan_clone (pre-clone preview) and apply_clone.

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?

Explicit when-to-use ('after apply_clone and after component changes') and names the alternative for the opposite case ('for a pre-clone preview use plan_clone'). Covers the routing decision completely.

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