feat(platform): add document_retrieve agent tool

[larryro]

Summary

• Add document_retrieve agent tool that retrieves document content from the knowledge base by ID with chunk-based pagination, complementing rag_search by providing sequential, structure-preserving document access
• Register tool in tool names, tool registry, and Knowledge category in UI tool selector
• Implement helper with access control, 60s fetch timeout, 50K char safety cap, and differentiated error handling
• Improve document tools UX: update descriptions to clarify when to use document_retrieve vs file extraction tools, move document_list to Knowledge category
• Add 24 tests covering happy path, pagination, truncation, access control, error handling, timeout, and schema validation

Refs #659

Test plan

• Verify document_retrieve returns correct content for a valid document ID
• Verify chunk-based pagination (chunkStart/chunkEnd) returns expected slices
• Verify access control rejects unauthorized requests
• Verify timeout and network error handling
• Verify tool appears in Knowledge category in the UI tool selector
• Run existing test suite: all 24 tests pass

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Introduced document_retrieve tool enabling retrieval of indexed document content with pagination support for handling large documents.
  • Reorganized tool categories to better group document and knowledge base tools.

• Documentation

  • Enhanced document_list tool descriptions with clearer guidance on appropriate use cases and alternative tools for specific tasks.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fe156962-5c5c-478e-a586-6084e8407ce6

📥 Commits

Reviewing files that changed from the base of the PR and between 794304d and 054ce15.

⛔ Files ignored due to path filters (1)

• services/platform/convex/_generated/api.d.ts is excluded by !**/_generated/**

📒 Files selected for processing (7)

• services/platform/app/features/custom-agents/components/tool-selector.tsx
• services/platform/convex/agent_tools/documents/__tests__/document_retrieve_tool.test.ts
• services/platform/convex/agent_tools/documents/document_list_tool.ts
• services/platform/convex/agent_tools/documents/document_retrieve_tool.ts
• services/platform/convex/agent_tools/documents/helpers/retrieve_document.ts
• services/platform/convex/agent_tools/tool_names.ts
• services/platform/convex/agent_tools/tool_registry.ts

---

📝 Walkthrough

Walkthrough

This PR introduces a new document_retrieve agent tool for retrieving indexed document content with pagination support. The implementation includes a tool definition with argument schema validation, a retrieval helper function with access control checks and timeout handling, a comprehensive test suite covering happy paths and error scenarios, and updates to tool categorization mappings, tool registry, and tool naming. Documentation in the document_list tool is updated to clarify the distinction between the new document_retrieve tool and file-based tools.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• feat(platform): Add document_retrieve agent tool with pagination #659: Directly implements the document_retrieve tool with schema, pagination, retrieval helper, registry, and name updates as proposed in this issue.
• feat(platform): Add document_list agent tool #658: Related through shared modifications to document tool registration surface and tool categorization updates.

Possibly related PRs

• Revamp custom agents: DB-backed defaults, unified chat, and delegation #506: Both PRs modify TOOL_CATEGORIES mappings in tool-selector.tsx to reorganize how tools are categorized across Documents and Knowledge categories.
• feat(agent): teach agents the email sending workflow pattern #71: Both PRs extend the agent tools registry and naming infrastructure (TOOL_NAMES and TOOL_REGISTRY) by adding new tool entries.
• feat(platform): consolidate excel tool and remove resource_check #471: Both PRs update TOOL_CATEGORIES in tool-selector.tsx to adjust the categorization and grouping of document-related tools.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding a new document_retrieve agent tool to the platform.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/659-document-retrieve-tool

---

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