Add frontend tools implementation guide to HTTP API docs

[aantn]

Summary

Added comprehensive documentation for implementing frontend tools in client applications, including step-by-step examples and best practices. Also reordered the navigation to prioritize the HTTP API reference.

Key Changes

• New implementation guide section: Added "Implementing Frontend Tools in Your Client" to the HTTP API documentation with 6 detailed steps covering:

  • Tool definition in requests
  • Streaming request setup
  • SSE stream parsing
  • Pause-mode tool call handling
  • Tool execution and stream resumption
  • Noop-mode (fire-and-forget) tool handling

• Code examples: Included practical JavaScript examples for each step, demonstrating:

  • Tool definition with parameters and modes
  • SSE event parsing and dispatching
  • Event handler implementation
  • Tool execution and result submission
  • Stream resumption with conversation history

• Implementation notes: Added critical guidance on:

  • Re-sending tool definitions on every request
  • Result serialization requirements (must be strings)
  • Conversation history handling for resumed streams
  • Mixed approval scenarios (both approvals and frontend tool calls)
  • Error handling patterns

• Navigation reordering: Moved "HTTP API" to the top of the reference documentation navigation for better discoverability

Implementation Details

The guide follows a progressive learning approach, building from basic tool definition through advanced scenarios like mixed pause types and error handling. All examples use realistic use cases (chart rendering, page navigation) to illustrate concepts clearly.

https://claude.ai/code/session_013fd6r27uVfY2RijXoJhJs2

Summary by CodeRabbit

• Documentation
  • Reordered reference navigation for clearer ordering.
  • Expanded HTTP API documentation with a new client guide for frontend tools: details the two-request pause/resume flow, batching and repeated pause-mode calls, noop-mode behavior, required client actions (resend tool list each request, include conversation history on resume, return tool results as JSON-encoded strings), and error/edge-case handling.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7a8d8ad8-df80-4cb7-bb62-da5dbfb5147c

📥 Commits

Reviewing files that changed from the base of the PR and between 5967826 and 45eb14a.

📒 Files selected for processing (1)

• docs/reference/http-api.md

✅ Files skipped from review due to trivial changes (1)

• docs/reference/http-api.md

---

Walkthrough

Reordered docs/reference/.nav.yml to place the HTTP API entry earlier in the navigation and expanded docs/reference/http-api.md with a detailed pause‑and‑resume two-request SSE flow for frontend pause-mode tools, multi-tool behavior, noop-mode notes, result/error encoding, and a client implementation guide.

Changes

Cohort / File(s)	Summary
Navigation docs/reference/.nav.yml	Moved the "HTTP API: http-api.md" entry higher in the reference navigation ordering.
HTTP API Documentation docs/reference/http-api.md	Added a new "Implementing Frontend Tools in Your Client" section and expanded frontend tool semantics: two-request pause/resume SSE flow (initial POST streams approval_required with pending_frontend_tool_calls + conversation_history; follow-up POST resumes with frontend_tool_results and conversation_history), handling of multiple pause-mode calls, noop-mode behavior, requirement that frontend_tool_results[].result be a JSON-encoded string, mixed pending approvals handling, and error-return conventions.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Server
    participant FrontendToolExecutor

    rect rgba(100, 150, 255, 0.5)
    Note over Client,Server: Request 1: Initial /api/chat with frontend_tools
    Client->>Server: POST /api/chat (SSE stream)
    Server->>Server: Process chat, detect pause-mode tool calls
    Server-->>Client: Stream events including approval_required (pending_frontend_tool_calls + conversation_history)
    Server-->>Client: Stream ends
    end

    rect rgba(100, 200, 100, 0.5)
    Note over Client,FrontendToolExecutor: Client-side execution
    Client->>FrontendToolExecutor: Execute pending frontend tools
    FrontendToolExecutor-->>Client: Return frontend_tool_results (JSON-encoded strings)
    end

    rect rgba(255, 180, 100, 0.5)
    Note over Client,Server: Request 2: Resume /api/chat with results
    Client->>Server: POST /api/chat (SSE) with conversation_history + frontend_tool_results
    Server->>Server: Resume processing using provided tool results
    Server-->>Client: Stream remaining response
    end

Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• Document tool approval behavior and update API reference #1800: Modifies the same HTTP API docs to describe approval_required pause-and-resume flow (overlaps on conversation_history and frontend_tool_results semantics).
• ROB-2405: document stream events #1073: Documents SSE streaming and approval_required/tool-calling event semantics referenced in this change.
• Add HTTP API documentation #592: Updates /api/chat HTTP API documentation and related streaming/event handling that intersect with these additions.

Suggested reviewers

• arikalon1
• moshemorad

🚥 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 title accurately reflects the main change: adding a frontend tools implementation guide to HTTP API docs, which aligns with the primary documentation addition in http-api.md.
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.}

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[netlify]

✅ Deploy Preview for holmes-docs ready!

Name	Link
🔨 Latest commit	45eb14a
🔍 Latest deploy log	https://app.netlify.com/projects/holmes-docs/deploys/69ccd95e843dd300085fe1d1
😎 Deploy Preview	https://deploy-preview-1867--holmes-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/http-api.md (1)

512-539: Consider clarifying the originalQuestion variable scope.

Line 534 references originalQuestion, but this variable is not defined in the function parameters or shown in scope. While this is example code, it might help to add a comment or parameter to clarify where this value should come from (e.g., stored from the initial request or passed as a parameter).

💡 Suggested clarification

-async function handleFrontendToolCalls(pendingCalls, conversationHistory) {
+async function handleFrontendToolCalls(pendingCalls, conversationHistory, originalQuestion) {
   const results = [];

   for (const call of pendingCalls) {

Or add a comment:

   // Request 2: resume the LLM with tool results
+  // originalQuestion should be saved from the initial request
   streamChat({
     ask: originalQuestion,

🤖 Prompt for AI Agents

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

In `@docs/reference/http-api.md` around lines 512 - 539, The example uses
originalQuestion inside handleFrontendToolCalls but originalQuestion is not
defined; update handleFrontendToolCalls to either accept originalQuestion as a
parameter (e.g., function handleFrontendToolCalls(pendingCalls,
conversationHistory, originalQuestion)) or add a clear inline comment above the
streamChat call explaining that originalQuestion must be captured from the
initial request scope and passed into this function, and ensure streamChat is
called with that passed-in value so references to originalQuestion (and the
streamChat call) are unambiguous.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@docs/reference/http-api.md`:
- Around line 512-539: The example uses originalQuestion inside
handleFrontendToolCalls but originalQuestion is not defined; update
handleFrontendToolCalls to either accept originalQuestion as a parameter (e.g.,
function handleFrontendToolCalls(pendingCalls, conversationHistory,
originalQuestion)) or add a clear inline comment above the streamChat call
explaining that originalQuestion must be captured from the initial request scope
and passed into this function, and ensure streamChat is called with that
passed-in value so references to originalQuestion (and the streamChat call) are
unambiguous.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ddc788ef-383f-4237-b77d-56c8b96506ab

📥 Commits

Reviewing files that changed from the base of the PR and between a142e15 and 2f1738e.

📒 Files selected for processing (2)

• docs/reference/.nav.yml
• docs/reference/http-api.md