fix(opencode): missing custom tool arg descriptions

[ashleytowner]

Issue for this PR

Closes #4357 & #15956

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

The issue is mostly described in the attached issue, but very simply it is twofold:

1. Description and other metadata isn't passed from the custom tool arg schema into the LLM context, resulting in bad tool calls. (This is only an issue for custom tools)
2. Tool args passed in from the LLM aren't actually checked against the schema, so bad parameters can go unnoticed.

The root problem is that Zod metadata from .describe() / .meta() is tied to Zod’s runtime registry. Custom tools can be loaded from a different runtime context than core, so metadata can be dropped during schema export unless it is re-registered in the core runtime before z.toJSONSchema(). Preserving that metadata restores argument descriptions in the model-visible schema.

The code I've added walks through the schema and re-registers metadata fields with the zod runtime in opencode, so that they actually get passed to the model. My code then also adds a step to actually check that args passed in from the model match the schema, so that invalid args can be rejected consistently.

How did you verify your code works?

Wrote an automated test (included in this PR) and tested manually by running opencode myself & seeing improvements, and seeing that it could quote me exactly the descriptions that I passed in.

Screenshots / recordings

This isn't applicable

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Hey! Your PR title Fix missing custom tool arg descriptions doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search results, I found 2 potentially related PRs:

1. PR fix(opencode): preserve custom tool arg descriptions in LLM prompts #13417 - "fix(opencode): preserve custom tool arg descriptions in LLM prompts"

   • fix(opencode): preserve custom tool arg descriptions in LLM prompts #13417
   • This appears to be addressing the same issue of preserving custom tool argument descriptions in LLM context

2. PR fix: preserve tool argument descriptions in schema conversion #14476 - "fix: preserve tool argument descriptions in schema conversion"

   • fix: preserve tool argument descriptions in schema conversion #14476
   • This also seems related to preserving tool argument descriptions during schema conversion, which aligns with the Zod metadata handling mentioned in PR fix(opencode): missing custom tool arg descriptions #15957

Note: These PRs may have been previously opened and closed/merged attempts at fixing the same issue (issue #15956). You should check their status and whether they fully addressed the problem or if there are unresolved aspects that PR #15957 is now fixing.

[ashleytowner]

The following comment was made by an LLM, it may be inaccurate:

Based on my search results, I found 2 potentially related PRs:

1. **PR [fix(opencode): preserve custom tool arg descriptions in LLM prompts #13417](https://github.com/anomalyco/opencode/pull/13417)** - "fix(opencode): preserve custom tool arg descriptions in LLM prompts"
   
   * [fix(opencode): preserve custom tool arg descriptions in LLM prompts #13417](https://github.com/anomalyco/opencode/pull/13417)
   * This appears to be addressing the same issue of preserving custom tool argument descriptions in LLM context

2. **PR [fix: preserve tool argument descriptions in schema conversion #14476](https://github.com/anomalyco/opencode/pull/14476)** - "fix: preserve tool argument descriptions in schema conversion"
   
   * [fix: preserve tool argument descriptions in schema conversion #14476](https://github.com/anomalyco/opencode/pull/14476)
   * This also seems related to preserving tool argument descriptions during schema conversion, which aligns with the Zod metadata handling mentioned in PR [fix(opencode): missing custom tool arg descriptions #15957](https://github.com/anomalyco/opencode/pull/15957)

Note: These PRs may have been previously opened and closed/merged attempts at fixing the same issue (issue #15956). You should check their status and whether they fully addressed the problem or if there are unresolved aspects that PR #15957 is now fixing.

Both of these linked PRs use the same solution (using zodToJsonSchema) but this doesn't actually work, because the zod-to-json-schema package doesn't support zod v4, and won't, because zod implements z.toJSONSchema which works in most cases, but not this case because of the bug mentioned above.

Here is a screenshot from #14476 showing the issue

[khimaros]

rebased against dev and small cleanup here: #19916