Skip to content

better tool input descriptions#2507

Merged
sawka merged 4 commits intomainfrom
sawka/waveai-toolinputdesc
Nov 2, 2025
Merged

better tool input descriptions#2507
sawka merged 4 commits intomainfrom
sawka/waveai-toolinputdesc

Conversation

@sawka
Copy link
Member

@sawka sawka commented Nov 2, 2025

better tool input descriptions, also fixes a bug with utf-8/base64 in the diff viewer.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 2, 2025

Caution

Review failed

The pull request is closed.

Walkthrough

This PR replaces the ToolInputDesc callback with an expanded ToolCallDesc(input any, output any, *UIMessageDataToolUse) string across aiusechat tool definitions and updates ToolDefinition accordingly. ResolveToolCall now accepts an explicit *ToolDefinition and recomputes ToolDesc after tool execution. Several tool definitions use the new output-aware description to reflect truncation/full-read states. Frontend decoding in aifilediff.tsx switched from atob() to base64ToString. Documentation (.roo/rules/rules.md) adds guidance to avoid atob()/btoa().

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

  • Verify uctypes.ToolDefinition field change (remove ToolInputDesc, add ToolCallDesc) and consistent signatures across implementations.
  • Confirm ResolveToolCall signature change and that callers pass the correct toolDef; ensure ToolDesc recomputation updates persisted/tool-use state correctly.
  • Inspect tools that use output-aware descriptions (readfile, readdir, screenshot, term, builder, tsunami, web, writefile) for correct truncation/full-read detection and message formatting.
  • Review new ToolAnyCallback additions in term tools for correctness and error handling.
  • Check frontend change in frontend/app/view/aifilediff/aifilediff.tsx imports base64ToString and decoding behavior.
  • Update/verify unit test changes (e.g., tools_readdir_test.go) reflect API rename.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Title Check ✅ Passed The PR title "better tool input descriptions" directly relates to the primary focus of the changeset, which involves replacing the ToolInputDesc field with ToolCallDesc across multiple tool definition files and updating the function signature to include additional parameters (output and toolUseData). The title accurately conveys the main theme of the changes—improving tool input descriptions through an API enhancement. While the word "better" is somewhat generic, it still meaningfully communicates the improvement without being vague enough to warrant an inconclusive rating. The title does not capture the secondary UTF-8/base64 bug fix mentioned in the PR description, but that appears to be a minor additional change rather than the primary focus.
Description Check ✅ Passed The PR description "better tool input descriptions, also fixes a bug with utf-8/base64 in the diff viewer" is clearly related to the changeset. It accurately references both the primary changes (tool input descriptions being improved through the ToolInputDesc to ToolCallDesc refactor) and a secondary change (the UTF-8/base64 fix in aifilediff.tsx and documentation). The description is concise but conveys meaningful information about what the PR addresses, meeting the lenient pass criteria for this check.

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3300308 and 1759df2.

📒 Files selected for processing (1)
  • pkg/aiusechat/tools_readdir_test.go (1 hunks)

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.5.0)

Error: unknown linters: 'unusedfunc,unusedparams', run 'golangci-lint help linters' to see the list of supported linters
The command is terminated due to an error: unknown linters: 'unusedfunc,unusedparams', run 'golangci-lint help linters' to see the list of supported linters


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a7d76d3 and 3300308.

📒 Files selected for processing (14)
  • .roo/rules/rules.md (1 hunks)
  • frontend/app/view/aifilediff/aifilediff.tsx (2 hunks)
  • pkg/aiusechat/openai/openai-backend.go (1 hunks)
  • pkg/aiusechat/tools_builder.go (3 hunks)
  • pkg/aiusechat/tools_readdir.go (1 hunks)
  • pkg/aiusechat/tools_readdir_test.go (1 hunks)
  • pkg/aiusechat/tools_readfile.go (3 hunks)
  • pkg/aiusechat/tools_screenshot.go (1 hunks)
  • pkg/aiusechat/tools_term.go (2 hunks)
  • pkg/aiusechat/tools_tsunami.go (3 hunks)
  • pkg/aiusechat/tools_web.go (2 hunks)
  • pkg/aiusechat/tools_writefile.go (3 hunks)
  • pkg/aiusechat/uctypes/usechat-types.go (1 hunks)
  • pkg/aiusechat/usechat.go (5 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: sawka
Repo: wavetermdev/waveterm PR: 2433
File: pkg/aiusechat/tools_readfile.go:197-197
Timestamp: 2025-10-15T03:21:02.229Z
Learning: In Wave Terminal's AI tool definitions (pkg/aiusechat/tools_*.go), the Description field should not mention approval requirements even when ToolApproval returns ApprovalNeedsApproval. This prevents the LLM from asking users for approval before calling the tool, avoiding redundant double-approval prompts since the runtime will enforce approval anyway.
📚 Learning: 2025-10-15T03:21:02.229Z
Learnt from: sawka
Repo: wavetermdev/waveterm PR: 2433
File: pkg/aiusechat/tools_readfile.go:197-197
Timestamp: 2025-10-15T03:21:02.229Z
Learning: In Wave Terminal's AI tool definitions (pkg/aiusechat/tools_*.go), the Description field should not mention approval requirements even when ToolApproval returns ApprovalNeedsApproval. This prevents the LLM from asking users for approval before calling the tool, avoiding redundant double-approval prompts since the runtime will enforce approval anyway.

Applied to files:

  • pkg/aiusechat/usechat.go
  • pkg/aiusechat/tools_screenshot.go
  • pkg/aiusechat/tools_writefile.go
  • pkg/aiusechat/tools_readdir_test.go
  • pkg/aiusechat/openai/openai-backend.go
  • pkg/aiusechat/uctypes/usechat-types.go
  • pkg/aiusechat/tools_web.go
  • pkg/aiusechat/tools_tsunami.go
  • pkg/aiusechat/tools_readfile.go
  • pkg/aiusechat/tools_readdir.go
  • pkg/aiusechat/tools_builder.go
  • pkg/aiusechat/tools_term.go
📚 Learning: 2025-01-23T06:09:05.334Z
Learnt from: esimkowitz
Repo: wavetermdev/waveterm PR: 1807
File: pkg/wshrpc/wshremote/wshremote.go:718-726
Timestamp: 2025-01-23T06:09:05.334Z
Learning: In Go, using a single if statement with the `&&` operator (e.g. `if x != nil && x.Field != nil`) is the idiomatic way to handle multiple nil checks. Avoid suggesting nested if statements as they make the code more verbose without adding value.

Applied to files:

  • pkg/aiusechat/tools_web.go
🧬 Code graph analysis (10)
frontend/app/view/aifilediff/aifilediff.tsx (1)
frontend/util/util.ts (1)
  • base64ToString (460-460)
pkg/aiusechat/usechat.go (1)
pkg/aiusechat/uctypes/usechat-types.go (3)
  • ToolDefinition (79-93)
  • WaveToolCall (171-176)
  • AIToolResult (294-299)
pkg/aiusechat/tools_screenshot.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_writefile.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_web.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_tsunami.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_readfile.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_readdir.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_builder.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
pkg/aiusechat/tools_term.go (1)
pkg/aiusechat/uctypes/usechat-types.go (1)
  • UIMessageDataToolUse (140-151)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: Analyze (javascript-typescript)
  • GitHub Check: Analyze (go)
  • GitHub Check: Build for TestDriver.ai
🔇 Additional comments (27)
frontend/app/view/aifilediff/aifilediff.tsx (2)

6-6: LGTM!

Correct import of the UTF-8-safe base64 decoding utility.


84-85: Excellent fix for UTF-8 handling!

Replacing atob() with base64ToString() correctly handles multi-byte UTF-8 characters in file contents. The native atob() only supports Latin-1/ASCII and would corrupt non-ASCII characters.

.roo/rules/rules.md (1)

44-45: LGTM!

Excellent addition to the coding guidelines. This prevents future UTF-8 bugs by directing developers to the centralized, UTF-8-safe base64 utilities.

pkg/aiusechat/openai/openai-backend.go (1)

942-944: LGTM!

The field rename from ToolInputDesc to ToolCallDesc is consistent with the expanded signature. Passing nil for output and toolUseData is correct at this point since the tool hasn't been executed yet.

pkg/aiusechat/tools_web.go (1)

73-79: LGTM!

The signature update for ToolCallDesc is correct. This tool doesn't need the output or toolUseData parameters for generating its description, which is fine—they're available if needed in the future.

pkg/aiusechat/tools_tsunami.go (3)

127-129: LGTM!

The signature update for ToolCallDesc in GetTsunamiGetDataToolDefinition is correct and consistent with the API changes.


152-154: LGTM!

The signature update for ToolCallDesc in GetTsunamiGetConfigToolDefinition is correct and consistent with the API changes.


185-187: LGTM!

The signature update for ToolCallDesc in GetTsunamiSetConfigToolDefinition is correct and consistent with the API changes.

pkg/aiusechat/tools_screenshot.go (1)

70-80: LGTM!

The signature update for ToolCallDesc in GetCaptureScreenshotToolDefinition is correct and consistent with the API changes.

pkg/aiusechat/usechat.go (5)

332-334: LGTM!

The comment clarifies that ToolVerifyInput can modify toolUseData, and the code correctly propagates those changes to both the frontend and chat store.


367-367: LGTM!

Passing toolDef explicitly to ResolveToolCall makes the function signature clearer and allows better control over which tool definition is used.


542-542: LGTM!

The updated ResolveToolCall signature accepts an explicit toolDef parameter, making dependencies clearer and allowing callers to pass the appropriate tool definition.


568-570: LGTM!

Recomputing the tool description after execution with the result is a key improvement. The tool description can now reflect the actual outcome (e.g., "read 500 lines from file.txt" instead of "reading file.txt").


584-586: LGTM!

Recomputing the tool description after ToolAnyCallback execution with the output object is consistent with the ToolTextCallback path and enables richer, result-aware descriptions.

pkg/aiusechat/tools_readdir.go (1)

109-127: LGTM!

Excellent use of the output parameter to provide context-aware descriptions. The description adapts based on whether the directory listing was truncated, giving users clear feedback about what the tool actually did.

pkg/aiusechat/tools_builder.go (3)

58-60: LGTM!

The signature update for ToolCallDesc in GetBuilderWriteAppFileToolDefinition is correct and consistent with the API changes.


145-151: LGTM!

The signature update for ToolCallDesc in GetBuilderEditAppFileToolDefinition is correct. The description includes the number of edits, providing useful context.


188-190: LGTM!

The signature update for ToolCallDesc in GetBuilderListFilesToolDefinition is correct and consistent with the API changes.

pkg/aiusechat/tools_writefile.go (3)

197-203: LGTM! Clean signature migration.

The ToolCallDesc signature has been correctly updated to match the new API. The implementation remains focused on input parsing, which is appropriate for this tool's description needs.


372-383: LGTM! Good descriptive formatting.

The ToolCallDesc correctly handles both singular and plural forms for edit counts, providing clear context about the operation.


485-491: LGTM!

The ToolCallDesc implementation is consistent with the other tool definitions in this file.

pkg/aiusechat/uctypes/usechat-types.go (1)

89-92: LGTM! Clear API contract documentation.

The updated comments clearly document the nil-ability contract for each callback, which is essential for implementers. The distinction between callbacks that always receive non-nil toolUseData (ToolAnyCallback, ToolVerifyInput) versus ToolCallDesc (where parameters may be nil) is well-documented.

pkg/aiusechat/tools_term.go (2)

181-213: LGTM! Well-structured tool definition.

The ToolCallDesc provides context-aware descriptions that vary based on whether default parameters are used, making the tool usage more transparent. The ToolAnyCallback implementation correctly delegates to the shared getTermScrollbackOutput helper.


261-299: LGTM! Comprehensive implementation.

The tool definition correctly implements both description and execution logic, with proper error handling for shell integration requirements.

pkg/aiusechat/tools_readfile.go (3)

285-287: LGTM! Comprehensive truncation detection.

Including both "read_limit" and StopReasonMaxBytes ensures the truncated field is set consistently regardless of which limit was hit.


321-327: LGTM! Good use of named constants.

Replacing magic numbers with the constants ReadFileDefaultLineCount and ReadFileDefaultMaxBytes improves maintainability and consistency with the values defined at the top of the file.


334-368: Excellent enhancement! Output-aware descriptions.

The ToolCallDesc now intelligently inspects the tool output to determine whether the entire file was read or truncated. This provides much clearer descriptions:

  • "entire file" when not truncated
  • "first/last N lines" when truncated or output unavailable

The nil-safe handling (lines 345-350) ensures graceful fallback if output is unavailable.

@sawka sawka merged commit b442b91 into main Nov 2, 2025
5 of 7 checks passed
@sawka sawka deleted the sawka/waveai-toolinputdesc branch November 2, 2025 20:34
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