opencode-workbench

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

Annotations already declare idempotentHint and destructiveHint, but the description adds real context: the consent gate requires confirm:true or nothing changes, present components are skipped, and it writes specific files with mode 600. It stops short of describing permissions/privilege requirements or rollback behavior for a mutation tool, so it is strong but not exhaustive.

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: the main action and its side effects come first, then the idempotency and consent caveats, then the routing rule. The long inline component list is information-dense rather than padding, though it does make the single paragraph heavy.

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, and the description still covers the mutation semantics, the consent gate, idempotency, the files produced, and the alternative tool. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it by explaining the semantics of the consent gate (returns a plan and no changes when confirm is absent) and by framing the components array as selecting a subset with per-component control. dryRun and the SSH target fields are left to 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?

It names a specific verb+resource (install the Workbench profile on a target by cloning and installing enumerated components) and enumerates the exact artifacts it produces (rendered opencode.json, mode-600 ~/.env.workbench). This differentiates it clearly from siblings like bootstrap_host and plan_clone without opening any schema.

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 routing: use this for a component subset or per-component control on an already-provisioned host; use bootstrap_host for a first-time provision; and do not call both for the same host and change. Both the when-to-use and the when-not-to-use alternative are stated.

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

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

Goes well beyond the annotations (openWorldHint, idempotentHint, destructiveHint): it discloses the consent gate ('without confirm:true it returns a plan and changes nothing'), that upgrade needs root/sudo, that upgrade defaults to plan-only, that secrets are never read or transmitted, and that help:true avoids contacting the target. These are exactly the behavioral traits an agent needs for a destructive provisioning call.

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 provisioning action and its sub-steps, then the consent/dry-run behavior, then the sibling exclusion. Every sentence carries weight, though the middle section is densely packed and could be split for 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?

For a complex, destructive, multi-step, SSH-capable tool with 11 params, nested target object, and an output schema, the description covers scope, consent, privilege requirements, secret handling, and alternative tools. Nothing material an agent needs before calling 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 baseline is 3, but the description adds real meaning: it explains the semantics of help:true (full docs, no target access), confirm:true (consent gate), and upgrade:true (root/sudo, plan-only default) in terms of behavior rather than just naming the flags.

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 ('Provision a bare Linux target end-to-end in one call') and enumerates the concrete steps performed (scan, dry-run plan, install OpenCode, apply VDD profile, verify parity). It explicitly distinguishes itself from the granular siblings, so an agent can select it without opening any schema.

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 ('first-time provision of a bare host') and when-not-to-use ('do NOT also call inspect_target, plan_clone, apply_clone, or install_component for the same host and change'), naming the four alternatives to use instead for step-by-step control.

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 non-obvious context the annotations cannot: it 'read[s] only the bundled profile' and works 'without contacting any target', which tells the agent there are no side effects or network dependencies. It stops short of describing caching or freshness behavior, so not a 5.

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

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

Three tight sentences, each earning its place, with the core purpose and read-only nature front-loaded before the routing guidance. No filler or repetition of the schema/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?

An output schema exists, so return values need not be explained; the description still summarizes the returned content categories. For a static, zero-param introspection tool, nothing an agent needs in order to call or avoid 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and no schema gap to compensate for. The baseline for a no-parameter tool applies.

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

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

Specific verb ('Describe this MCP server') and resource (the bundled server profile), and it enumerates exactly what is returned: repository URL, default component set, tier grouping, and MCP add-ons. It is clearly distinguishable from the sibling that inspects live machines.

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

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

Explicitly states when to use it ('Use it first to look up a component id for install_component or to see available add-ons') and names the alternative with its selecting condition ('use inspect_target for a machine's live state'). Both the primary use and the exclusion are spelled out.

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, so the safety profile is partly covered. The description still adds real value beyond them: 'one shell probe, changes nothing', 'installs nothing', and the security-relevant detail that credentials are reported by name and never by value. It does not discuss failure modes when SSH is unreachable or probe cost/latency.

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

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

A single dense paragraph that front-loads what is probed and what is returned, then moves to routing and safety. Every clause carries information, though the long output enumeration makes it slightly heavier than necessary given 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?

Output schema exists, so return values need not be explained, yet the description still names the key fields. Combined with explicit read-only/no-install guarantees, sibling routing, and full param coverage, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the nested target object and its mode/host/user/port/identityFile fields are already fully documented. The description only restates the local/ssh distinction already in the enum descriptions and adds no SSH syntax, default, or precedence detail beyond the schema.

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

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

States a specific verb (probe) and resource (one Linux machine, local or SSH) and enumerates exactly what it reports: OS, kernel, architecture, package manager, Node/npm, OpenCode, Docker, per-tool flags, and credential names. This is precise enough to distinguish it from list_required_credentials and plan_clone without opening any schema.

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 to see what a clone would touch, then plan_clone for an ordered plan, and bootstrap_host for first-time end-to-end provisioning. Both the when-to-use condition and the named alternatives are present.

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

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

Annotations already declare idempotentHint and destructiveHint, so the 'Idempotent' claim is partly redundant, but the description adds genuinely new behavior: the consent gate ('without confirm:true it returns the plan'), which explains the dry-run semantics an agent must know before mutating a host. It does not cover credential/permission requirements or SSH auth failure modes, which list_required_credentials and run_auth_flow imply are relevant.

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

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

A dense but well-ordered paragraph: what it does, the consent/idempotency contract, then routing to siblings. Every clause carries information, though the idempotent/consent sentence and the routing sentence could be split for faster scanning.

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 scope, consent behavior, and sibling routing adequately for a 4-param install tool. The main remaining gap is prerequisites — which credentials the target needs and when to call list_required_credentials first.

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 target/mode/confirm/component are already documented in the schema. The description restates that component must come from get_workbench_info and repeats the confirm plan behavior rather than adding format or constraint detail (e.g. workspace/profile repo semantics). 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 (Install) plus resource (a single Workbench component) with concrete id examples, and explicitly distinguishes itself from apply_clone (subset) and bootstrap_host (first-time provision). An agent can select it without opening any sibling schema.

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 explicit routing rules: 'Use it for one targeted component; use apply_clone for a component subset, or bootstrap_host for a first-time end-to-end provision', plus an anti-pattern warning ('do not combine them for the same host and change'). This is textbook when-to-use 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 readOnly/idempotent/openWorld, but the description adds the crucial non-obvious trait 'Value-blind: checks only whether env vars are set and never reads or returns values.' This is behavioral context the structured fields cannot convey, plus what output to expect (label, purpose, provider URL, method, command).

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

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

Three dense sentences, front-loaded with the core action, then the key non-obvious constraint (value-blind), then usage guidance. No filler.

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

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

For a read-only inspection tool with annotations, an output schema, and full schema coverage, the description covers everything an agent needs: result contents, the safety-critical value-blind guarantee, and the workflow position (after plan_clone, alongside run_auth_flow).

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 rich nested descriptions (mode, host, port, user, identityFile, cwd), so the schema already handles parameter semantics. The description adds only implicit context about 'the profile' and 'the target,' which is marginal but slightly helpful.

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 precise verb+resource: it lists required credentials plus their present/missing status and acquisition details. The parenthetical enumerates exactly what is returned, so an agent can distinguish it from siblings like run_auth_flow (which acts on a credential) or plan_clone (which plans the 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 plan_clone to see what a clone would leave degraded') and names the pairing tool ('pair it with run_auth_flow to act on one credential'), giving both the trigger and the follow-up action.

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, so the safety profile is covered, but the description adds genuinely new context: 'installs nothing', the SSH prerequisite for mode=ssh, and that privileged-command previews are returned. It does not cover failure modes or permission requirements beyond SSH, so it stops short of a 5.

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 and output vocabulary are front-loaded, then routing guidance, then the read-only caveat. It is a single dense paragraph, so it is efficient but slightly packed with semicolon-joined clauses rather than clearly separated lines.

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 annotations covering the safety profile, a fully described schema, and an output schema handling return values, the description only needs to supply purpose, routing and the read-only/SSH caveat – all present. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including the nested target object is already documented. The description reinforces one constraint (SSH needed for mode: ssh) but adds no syntax or default semantics beyond the schema. 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+resource ('Compare a target against the portable Workbench profile') and names the exact output classification (install/present/manual), which immediately separates it from apply_clone, inspect_target and verify_clone. An agent can identify the tool's job without opening the schema.

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 explicit when-to-use ('before apply_clone for granular control of an existing profile') and when-to-use-something-else ('for a first-time end-to-end provision use bootstrap_host instead'), even explaining what bootstrap_host composes. Both alternatives and the selecting condition are named.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered; the description adds substantive behavior beyond them: it returns a plan rather than executing, never handles secret values, and does not run interactive flows ('emit-and-verify', 'best-effort'). It does not describe error/fallback behavior when no command exists, which is the remaining gap.

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

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

Dense and front-loaded: the return contents come first, then the behavioral limit, then the usage routing. Terminology like 'emit-and-verify' is slightly jargon-heavy but each clause carries information.

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

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

An output schema exists, so return values need not be re-explained, and annotations cover the safety profile; the description still supplies the conceptual model (plan vs execution, no secrets) and the sibling relationship. Nothing an agent needs to select or invoke it appears missing.

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

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

Schema description coverage is 100% and the nested target object is fully documented, so the schema carries the burden; baseline 3 applies. The description's mention that the credential comes from list_required_credentials largely repeats what the `var` schema description already states.

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

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

States a concrete verb and resource: returns the acquisition plan for one credential on a target, enumerating what the plan contains (provider URL, non-interactive command, presence flag). It also preempts the misleading name by clarifying it does not run interactive flows, and distinguishes itself from list_required_credentials.

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 explicit routing: use it for a single credential surfaced by list_required_credentials, and states it does not replace that listing. It lacks an explicit when-not-to-use for other cases (e.g. multi-credential setup vs apply_clone/install_component), but the primary alternative is named.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds useful context beyond that: it needs SSH for mode: ssh, it verifies specific files, it re-detects every component, and it returns a missing list. It stops short of richer operational details such as failure handling, but output schema likely covers the return shape.

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

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

The description is compact and front-loaded: purpose first, then read-only/SSH constraint, then usage guidance and alternatives. Every sentence carries distinct information and none is redundant.

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

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

Given the tool's complexity, rich nested schema, annotations, and an output schema, the description supplies everything needed for correct selection and invocation. It covers purpose, prerequisites, automation context, sibling alternatives, and the key SSH caveat.

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 all six parameters, including the nested target fields. The description only moderately reinforces target and mode: ssh behavior, adding little meaning beyond what is already in the schema for dryRun, skipRepo, workspace, components, and profileUrl.

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: re-check a target after a clone, confirm two expected files exist, and re-detect components returning the missing list. It clearly distinguishes this from apply_clone and plan_clone by naming their roles.

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

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

It explicitly says to use it after apply_clone, notes that bootstrap_host runs it automatically, and says to call verify_clone directly only for a targeted re-check. It also points to plan_clone for a pre-clone preview, covering when and when-not to use it.

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