Fix: Preserve tool parameter descriptions in schema conversion

[trry-hub]

Summary

Fixes #4357

This PR fixes an issue where tool parameter descriptions (.describe()) were being lost during schema conversion, preventing the LLM from understanding what tool parameters are for.

Changes

• Replace z.toJSONSchema() with zodToJsonSchema() in packages/opencode/src/session/prompt.ts (line 788)
• Add import for zodToJsonSchema from zod-to-json-schema package

Why This Fix?

• z.toJSONSchema() is Zod's built-in method but doesn't preserve .describe() metadata
• zodToJsonSchema() from zod-to-json-schema package correctly preserves all metadata
• This aligns with the approach already used in server.ts

Impact

• ✅ Minimal change (1 line + 1 import)
• ✅ Consistent with existing codebase patterns
• ✅ No breaking changes
• ✅ Improves developer experience with custom tools

Testing

Created a test tool with parameter descriptions and verified that:

1. Tool compiles without errors
2. TypeScript type checking passes
3. Parameter descriptions will be available to the LLM

Example

Before this fix:

// Tool definition
args: {
  text: z.string().describe("The text to process")
}
// LLM sees: just a string parameter, no description

After this fix:

// Tool definition
args: {
  text: z.string().describe("The text to process")
}
// LLM sees: string parameter with description "The text to process"

[github-actions]

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

• PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Hey! Your PR title Fix: Preserve tool parameter descriptions in schema conversion 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:

Found Potential Duplicates

There are 2 related PRs addressing similar issues:

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

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

These PRs appear to address the same or very similar issue - preserving tool parameter/argument descriptions. PR #14476 in particular has an identical title focus on schema conversion. You should review whether these PRs were already merged, closed, or if #15945 supersedes them with additional fixes.

[trry-hub]

Closing this PR in favor of #14476 which has identical changes and was submitted earlier on 2026-02-20.

Both PRs fix the same issue (#4357) with the same code changes - replacing z.toJSONSchema() with zodToJsonSchema() to preserve tool parameter descriptions.

Thanks to @Hemanshu-Upadhyay for the earlier contribution! 🙏