Documentation needed for CLI Built-in Tools including new Report Failure Tool

[continue]

Summary

Recent feature merges have introduced new CLI built-in tools that are not yet documented. Most notably, PR #8694 (merged Nov 14, 2025) added a "Report Failure" tool as a tier 2 feature, but there is no user-facing documentation explaining this or other CLI-specific built-in tools.

Problem

The Continue CLI has 11 built-in tools available to agents (found in extensions/cli/src/tools/allBuiltIns.ts), but the documentation lacks a comprehensive reference for these tools:

Currently Undocumented CLI Built-in Tools:

1. reportFailureTool (NEW - tier 2 feature) - Allows agents to report task failures with error messages
2. exitTool - Allows agents to exit gracefully
3. writeChecklistTool - Creates task checklists
4. listFilesTool - Lists directory contents
5. searchCodeTool - Searches codebase for patterns
6. multiEditTool - Makes multiple file edits
7. editTool - Single file editing
8. writeFileTool - Creates/overwrites files
9. readFileTool - Reads file contents
10. runTerminalCommandTool - Executes terminal commands
11. fetchTool - Fetches URLs

Current Documentation Gaps:

1. CLI-specific tools are not documented in:

   • /docs/cli/overview.mdx - Only mentions tool permission levels generically
   • /docs/cli/quick-start.mdx - Only mentions writeFile and runTerminalCommand as examples

2. IDE extension tools are documented in:

   • /docs/ide-extensions/agent/how-it-works.mdx - Lists IDE tools but not CLI-specific ones
   • /docs/ide-extensions/plan/how-it-works.mdx - Lists read-only tools for Plan mode

3. Agent documentation in /docs/hub/agents/ mentions "tools" but doesn't detail what built-in CLI tools are available

Recent Feature Without Documentation

PR #8694: Report Failure Tool (merged Nov 14, 2025)

• Adds ReportFailure built-in tool for CLI agents
• Allows agents to report task failures with error messages
• Posts FAILED status to agents/{id}/status endpoint
• Auto-reports on non-retryable errors or exhausted retries
• Tier 2 feature ("Important feature that adds new capabilities")
• No documentation exists for this feature

Proposed Solution

Create comprehensive CLI tools documentation covering:

1. New Page: /docs/cli/built-in-tools.mdx

Create a dedicated reference page for CLI built-in tools that includes:

• Overview of CLI built-in tools vs IDE tools
• Tool Permission Levels (allow, ask, exclude) and TUI vs headless differences
• Complete Tool Reference with:
  • Tool name and display name
  • Description and purpose
  • Parameters and schemas
  • Examples of usage
  • Permission level (readonly/allow/ask)
  • When to use each tool

2. Document Report Failure Tool

Add specific documentation for the new ReportFailure tool:

• Purpose: Allow agents to gracefully fail with error messages
• When to use: Unrecoverable errors, task cannot be completed
• Parameters: errorMessage (required string)
• Behavior: Posts FAILED status, logs to Sentry, notifies user
• Auto-invocation: Triggered on non-retryable errors or exhausted retries

3. Update Existing Documentation

Update cross-references in:

• /docs/cli/overview.mdx - Link to built-in tools reference
• /docs/cli/quick-start.mdx - Reference the tools page
• /docs/hub/agents/create-and-edit.mdx - Clarify built-in vs MCP tools
• /docs/ide-extensions/agent/how-it-works.mdx - Distinguish IDE vs CLI tools

4. Add Examples

Include practical examples:

• Agent using ReportFailure when encountering unrecoverable errors
• Workflows using writeChecklist for task tracking
• exitTool for graceful agent completion
• searchCodeTool + multiEditTool for refactoring workflows

Acceptance Criteria

• Create /docs/cli/built-in-tools.mdx with complete tool reference
• Document all 11 CLI built-in tools with examples
• Highlight the new ReportFailure tool (tier 2 feature)
• Update navigation in docs/docs.json
• Add cross-references in CLI and agent documentation
• Include tool permission matrix (TUI vs headless mode)
• Add practical usage examples for each tool category

Additional Context

Files to Reference:

• extensions/cli/src/tools/allBuiltIns.ts - List of all tools
• extensions/cli/src/tools/reportFailure.ts - New feature implementation
• extensions/cli/src/tools/*.ts - Individual tool implementations

Related PRs:

• feat: report failure tool #8694 - feat: report failure tool (merged Nov 14, 2025)

Documentation Standards:

• Follow markdown format established in existing docs
• Use descriptive titles and clear sections
• Include code examples and practical use cases
• Add relevant navigation entries to docs.json

---

Generated with Continue

Co-Authored-By: Continue noreply@continue.dev

This agent session was co-authored by bekahhw and Continue.