feat(platform): add document_list agent tool

[larryro]

Summary

• Add a new document_list agent tool that allows AI agents to browse and list documents by team, folder, date range, and search query with offset-based pagination
• Implement list_documents_for_agent Convex query with robust validation, case-insensitive sorting, breadcrumb paths, and structured warnings for unauthorized teams or missing folders
• Categorize the new tool under "Documents" in the tool selector UI

Test plan

• Unit tests for document_list_tool (parameter validation, pagination, formatting)
• Comprehensive tests for list_documents_for_agent (filtering, sorting, edge cases, authorization, date validation)
• Verify tool appears in the Documents category in the agent tool selector
• End-to-end test: configure an agent with document_list and confirm it can list documents

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added document listing tool with filtering capabilities (folder path, extension, date range, team, text search).
  • Support for sorting by creation date or name.
  • Cursor-based pagination with configurable result limits.

• Tests

  • Added comprehensive test coverage for document listing, filtering, sorting, pagination, and access control validation.

[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

📝 Walkthrough

Walkthrough

The PR implements a new document_list agent tool. It adds a Zod-based argument schema supporting filters (folderPath, extension, dateFrom, dateTo, query, teamId), sorting (by createdAt or name), and pagination (limit, cursor). The tool is registered in the agent tools registry and listed in the UI tool selector. The implementation chain includes a public listDocuments helper that validates inputs and invokes an internal Convex query listForAgent, which retrieves user team IDs and delegates to listDocumentsForAgentHelper for document retrieval with access control, folder path resolution, filtering, sorting, and cursor-based pagination. Comprehensive test suites cover argument validation, helper behavior, and end-to-end listing scenarios including filtering, sorting, pagination, and edge cases.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• feat(platform): Add document_list agent tool #658: Directly implements the feature to add the document_list agent tool with argument schema, tool definition, and internal query registration.
• test(platform): Add tests for document_list and document_retrieve tools #661: Directly addresses the requirement for comprehensive tests covering document listing behavior, filtering, sorting, pagination, and argument validation.

Possibly related PRs

• refactor: replace folderPath with folders table and folderId #711: Modifies the same document listing codepaths (list_documents_for_agent, internal_queries, folder resolution) that this PR implements, suggesting shared refactoring or feature integration.
• feat: Enhance LLM node with structured JSON output and refactor agent tools #24: Both PRs modify the Convex agent tools registry and tool names constants to register and expose new agent tools.
• feat(platform): consolidate excel tool and remove resource_check #471: Both PRs update TOOL_CATEGORIES in tool-selector to expose the document listing capability in the UI.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% 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 pull request title 'feat(platform): add document_list agent tool' accurately and clearly describes the main change: adding a new document_list agent tool to enable AI agents to browse and list documents.

_{✏️ 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/658-document-list-agent-tool

---

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