Repository navigation
feat(ai): add tool_docs meta-tool with per-category usage guides - #1411
2witstudios wants to merge 4 commits into
Conversation
Agents that discover tools via tool_search only received JSON schemas, giving them no guidance on usage patterns, data models, or common mistakes. This meant first-attempt failures on tools like edit_sheet_cells (A1 addressing), update_task (status group system), and create_calendar_event (recurrence rules + timezone handling). - Add tool_docs non-core tool: accepts a typed category enum and returns a markdown guide covering concept, data model, workflows, and mistakes - Add docs/index.ts with inline content for 7 categories: pages, task-lists, sheets, calendar, agents, channels, drives - Extend tool_search responses with docs_available + docs_hint on tools that have a matching category (30 tools mapped) - Update TOOL_DISCOVERY_PROMPT and buildNonCoreToolNamesPrompt to mention tool_docs - Wire tool_docs into finalTools in the global assistant messages route - Suppress tool_docs calls in ToolCallRenderer and CompactToolCallRenderer Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
Your plan includes 1 review of capacity. Refill in 47 minutes and 2 seconds. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more review capacity refills, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughIntroduces a new ChangesTool Documentation Discovery System
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ec6cf71dc6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/web/src/lib/ai/core/system-prompt.ts`:
- Line 41: The prompt instructs the model to call tool_docs({category}) with
values from CATEGORY_MAP that don't match the tool_docs enum; update
CATEGORY_MAP (or the prompt) so categories map to the exact enum values expected
by tool_docs (e.g., map "tasks"->"task-lists", "drive"->"drives"), or change the
prompt to transform values before calling tool_docs; locate CATEGORY_MAP and the
prompt string using the symbols CATEGORY_MAP and tool_docs in system-prompt.ts
and ensure the category names produced/used match the tool_docs API exactly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 52d05601-7644-4e03-b65a-db589dd56a64
📒 Files selected for processing (7)
apps/web/src/app/api/ai/global/[id]/messages/route.tsapps/web/src/components/ai/shared/chat/tool-calls/CompactToolCallRenderer.tsxapps/web/src/components/ai/shared/chat/tool-calls/ToolCallRenderer.tsxapps/web/src/lib/ai/core/system-prompt.tsapps/web/src/lib/ai/docs/index.tsapps/web/src/lib/ai/tools/tool-docs-tool.tsapps/web/src/lib/ai/tools/tool-search-tool.ts
CATEGORY_MAP was using 'drive', 'tasks', and grouping edit_sheet_cells
under 'pages' — none of which matched tool_docs categories ('drives',
'task-lists', 'sheets'). Agents reading the non-core tools listing would
call tool_docs({category:"tasks"}) and get a not-found error.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
update_task creation takes pageId (the TASK_LIST page's own ID), not the internal taskListId DB field. Also adds create_task_status workflow example and fixes the 'common mistakes' section accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The tool is documented in task-lists.md but was not listed in the non-core tools prompt or given a docs_hint in tool_search results. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Summary
tool_docsnon-core tool that agents can call to get rich usage documentation (concept, data model, workflows, common mistakes) for any tool category before calling tools they're unfamiliar withtool_searchresponses to includedocs_available: trueand adocs_hintinline on relevant tool results (30 tools mapped across 7 categories), so agents see the hint at the exact moment they pull a schematool_docsalongsidetool_searchProblem
Agents discovering tools via
tool_searchonly received JSON schemas — no usage guidance. This caused first-attempt failures on:edit_sheet_cells(A1 addressing isn't obvious),update_task(status group system requiresread_pagefirst),create_calendar_event(recurrence rules, timezone requirement), and general page hierarchy patterns.Changes
New files:
apps/web/src/lib/ai/docs/index.ts— Inline documentation for 7 categories:pages,task-lists,sheets,calendar,agents,channels,drivesapps/web/src/lib/ai/tools/tool-docs-tool.ts—tool_docstool implementationModified files:
tool-search-tool.ts— AddedDOCS_HINT_MAP(30 tool→category entries); matching tools in results getdocs_available + docs_hintsystem-prompt.ts— UpdatedTOOL_DISCOVERY_PROMPTandbuildNonCoreToolNamesPromptheader to mentiontool_docsmessages/route.ts— Wiredtool_docs: createToolDocsTool()intofinalToolsToolCallRenderer.tsx+CompactToolCallRenderer.tsx— Suppresstool_docscalls from UI (invisible to users)Agent workflow after this change
tool_search("select:update_task")→ gets schema +docs_hinttool_docs({category:"task-lists"})→ gets status group system, nested FOLDER+TASK_LIST patterns, mandatoryread_page-first workflowexecute_tool("update_task", {...})correctly on the first attemptTest plan
tool_search("select:edit_sheet_cells")in a chat — confirm response includesdocs_hintpointing to"sheets"tool_docs({category:"sheets"})— confirm A1 addressing explanation is returnedtool_docs({category:"task-lists"})— confirm status group system and nested org pattern appeartool_docscalls produce no visible card in the chat UItool_docsmention in the NON-CORE TOOLS section🤖 Generated with Claude Code
Summary by CodeRabbit