feat(platform): require explicit user request for file generate operations

[larryro]

Summary

• Adds guard instructions to all file tool descriptions (DOCX, Excel, PDF, PPTX, text) to prevent the agent from proactively calling the "generate" operation unless the user explicitly requests that file format.

Test plan

• Verify agent does not proactively generate files when user hasn't requested a specific format
• Verify agent still generates files correctly when explicitly asked (e.g., "export as PDF")

Summary by CodeRabbit

• Documentation
  • Clarified instructions for file export tools (Word, Excel, PDF, PowerPoint, and text) to ensure proper AI agent behavior when generating files.

[greptile-apps]

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

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates the tool descriptions for five file export tools (DOCX, Excel, PDF, PPTX, and text) to add explicit instructions that the "generate" operation should only be invoked when users explicitly request file creation or export. The changes are purely descriptive and do not modify any runtime logic, argument schemas, control flow, or execution behavior.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• feat(platform): consolidate excel tool and remove resource_check #471: Updates the Excel tool description to add the same "generate" operation constraint instruction.
• feat(agent): generate file download cards in chat via appendFilePart #810: Modifies the same file tool descriptions (docx, excel, pdf, pptx, text) and includes additional runtime logic changes like appendFilePart and generate-path logic.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding guard instructions to file tool descriptions that require explicit user requests before calling generate operations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/file-tools-explicit-generate-guard

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@services/platform/convex/agent_tools/files/pdf_tool.ts`:
- Line 41: The agent system prompt in file agent.ts still instructs the agent to
"Generate with reasonable defaults" and "Choose appropriate formats
automatically", which conflicts with the new guard in pdf_tool.ts that requires
explicit user requests to call the "generate" operation; update the agent system
prompt (the string or constant that composes the file agent instructions, e.g.,
the SYSTEM_PROMPT or buildAgentPrompt function in the file agent module) to
remove any phrasing that allows automatic PDF creation and instead explicitly
require that the agent call the PDF tool's "generate" operation only when the
user explicitly asks to create or export a PDF; ensure the prompt language
mirrors the guard in pdf_tool.ts so the agent will not choose formats or invoke
generate proactively.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 17b12e11-e4e0-404d-afbe-d61f7c6eed46

📥 Commits

Reviewing files that changed from the base of the PR and between fcbae6f and 0956298.

📒 Files selected for processing (5)

• services/platform/convex/agent_tools/files/docx_tool.ts
• services/platform/convex/agent_tools/files/excel_tool.ts
• services/platform/convex/agent_tools/files/pdf_tool.ts
• services/platform/convex/agent_tools/files/pptx_tool.ts
• services/platform/convex/agent_tools/files/text_tool.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Conflicting agent instructions can still trigger proactive PDF generation.

Line 41 adds the right guard, but it conflicts with services/platform/convex/agents/file/agent.ts (“Generate with reasonable defaults” / “Choose appropriate formats automatically”). With both present, behavior is ambiguous and the PR objective (“require explicit user request”) is not reliably enforced. Please align the file-agent system prompt with this new rule so “generate” is only used on explicit user request.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/platform/convex/agent_tools/files/pdf_tool.ts` at line 41, The agent
system prompt in file agent.ts still instructs the agent to "Generate with
reasonable defaults" and "Choose appropriate formats automatically", which
conflicts with the new guard in pdf_tool.ts that requires explicit user requests
to call the "generate" operation; update the agent system prompt (the string or
constant that composes the file agent instructions, e.g., the SYSTEM_PROMPT or
buildAgentPrompt function in the file agent module) to remove any phrasing that
allows automatic PDF creation and instead explicitly require that the agent call
the PDF tool's "generate" operation only when the user explicitly asks to create
or export a PDF; ensure the prompt language mirrors the guard in pdf_tool.ts so
the agent will not choose formats or invoke generate proactively.