Skip to content

fix(opencode): surface workflow descriptions to LLM via tool description#280

Merged
mrsimpson merged 2 commits into
mainfrom
fix/opencode-plugin-parameter-descriptions
May 7, 2026
Merged

fix(opencode): surface workflow descriptions to LLM via tool description#280
mrsimpson merged 2 commits into
mainfrom
fix/opencode-plugin-parameter-descriptions

Conversation

@mrsimpson
Copy link
Copy Markdown
Collaborator

Problem

OpenCode does not propagate Zod parameter .describe() text to the LLM. This meant the AI had no guidance on which workflow enum value to pick when calling start_development, leading to wrong workflow selection.

Root cause confirmed: Hardcoding a canary string via .describe() was completely invisible to the LLM — parameter descriptions are simply never surfaced by OpenCode, regardless of Zod version or registry.

Solution

Embed the workflow enum choices and their descriptions directly in the tool description string — the only channel confirmed to reach the LLM:

Start a development workflow.

workflow parameter — available values:
  - epcc: EPCC — <description>
  - bugfix: Bugfix — <description>
  - custom: Use a custom workflow name

Changes

  • start-development.ts: Build tool description with inline workflow list; remove .describe() from workflow arg; remove unused generateWorkflowDescription import
  • plugin.ts: Remove tool.definition hook (was attempting to bridge Zod registries — wrong approach)
  • Development plan updated with full research trail of all 13 investigated approaches

Testing

All 286 tests pass. Verified the description is visible to the LLM after restart.

mrsimpson added 2 commits May 7, 2026 20:43
Documents all 13 investigated approaches to obtaining host's globalRegistry,
Zod v4 internals (how descriptions are stored/read), and why the dynamic import
approach was chosen as the production-viable solution.
…ribe()

OpenCode does not propagate Zod parameter .describe() text to the LLM.
Confirmed by canary test - descriptions are invisible regardless of zod
instance or registry. The tool description IS propagated, so embed the
workflow enum choices and their descriptions there directly.

Also removes the tool.definition hook and globalRegistry bridging code
which were solving the wrong problem.
@mrsimpson mrsimpson changed the title fix: surface workflow descriptions to LLM via tool description fix(opencode): surface workflow descriptions to LLM via tool description May 7, 2026
@mrsimpson mrsimpson merged commit 1bf74b1 into main May 7, 2026
3 checks passed
@mrsimpson mrsimpson deleted the fix/opencode-plugin-parameter-descriptions branch May 7, 2026 18:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant