docs(chat-api): document tool call names in the response stream (CUB-3108)

[vasilev-alex]

Summary

Addresses CUB-3108:

• toolCall.name values — new Tool names section states the set is open and evolving (not a fixed, versioned list), advises handling unknown names gracefully, and adds a table of common tool names visible in the response stream with what each one means.
• Adds a note that the documented request body fields are the complete public contract of the Chat API; any other fields are ignored or resolved automatically on the server and should not be sent.

🤖 Generated with Claude Code

[claude]

Claude finished @vasilev-alex's task in 33s —— View job

---

Code Review

Docs-only change; no issues found — expand for details

• Read the diff
• Verify content against docs-mintlify/CLAUDE.md conventions
• Check anchors, links, and Mintlify component usage

Verdict: LGTM. This is a well-scoped docs-only addition to docs-mintlify/reference/embed-apis/chat-api.mdx (+75/−0). The three new pieces — the <Info> pointer at the request-body table, the Internal request fields section, and the Tool names subsection with its table — fit cleanly into the existing structure and follow the repo's Mintlify conventions.

Notes:

• Anchor targets are correct. The new <Info> block on L207 links to #internal-request-fields, matching the ### Internal request fields heading Mintlify will slugify to that anchor. The intra-section link to #path-parameters (L320) also matches the existing ### Path Parameters heading.
• Naming conventions respected. Uses "Core Data APIs" (not "REST API") and links via the root-relative /reference/core-data-apis path — matches docs-mintlify/CLAUDE.md.
• Tone/structure consistent. The internal-fields list mirrors the style of the existing Request Body list; the tool-names table matches the format used elsewhere in the file.
• Content aligns with PR description. context overwrite to external, agentId path vs. body distinction, cubeCredentials resolution from auth mode, and the "open, evolving" framing for tool names are all consistent with what the PR body claims was verified against ai-engineer.

Minor optional nits (non-blocking, feel free to ignore):

• L322–324 groups workbookId, workbookContext, dashboardContext, isDevMode into one bullet labeled "Carry UI state" — that's fine, but if a future reader searches for isDevMode specifically they'll land on a fairly terse entry. A one-line-per-field breakdown would be more scannable, at the cost of a few more lines. Current form is defensible since these truly are irrelevant for external callers.
• L316: "selects the agent's runtime and toolset accordingly" is slightly abstract; a parenthetical example (e.g., "e.g., workbook, dashboard, mcp") would make it more concrete. Optional.

No correctness, security, or link-integrity issues. Approving in spirit — happy to merge.

• Branch: [alex/cub-3108-document-the-stream-chat-state-endpoint-better](https://github.com/cube-js/cube/tree/alex/cub-3108-document-the-stream-chat-state-endpoint-better)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jul 15, 2026, 8:53 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟡 Building	–	Jul 15, 2026, 8:51 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @vasilev-alex's task in 1m 30s —— View job

---

Code Review

LGTM — docs-only change; one note on PR/diff scope mismatch (expand for details)

• Fetch and read the actual diff (git show afa5d64)
• Verify anchors, links, and Mintlify component usage
• Check content against docs-mintlify/CLAUDE.md conventions
• Compare diff contents against PR description

Verdict: LGTM. The diff on this branch is a clean +37/-0 docs-only change to docs-mintlify/reference/embed-apis/chat-api.mdx:

1. A new <Info> block after the Request Body section stating that the documented fields are the complete public contract and any other fields are ignored/resolved server-side.
2. A new #### Tool names subsection under Tool Call Handling, explaining the toolCall.name set is open and evolving, with a table of common tool names.

Both additions follow repo conventions (Mintlify <Info> component with blank lines inside; root-relative internal links; no H1; sensible heading depth).

Anchor & link check:

• [cubeMeta](#cubemeta) → matches #### cubeMeta at L617 ✅
• [cubeSqlApi](#cubesqlapi) → matches #### cubeSqlApi at L714 ✅
• /admin/ai/certified-queries and /admin/ai/skills are root-relative as required ✅

One thing worth flagging — PR description vs actual diff:

The PR body describes four changes: cubeCredentials, agentId in URL vs body, context overwrite to external, and toolCall.name values. Only the last is actually present in this branch's diff against origin/master (plus the generic "complete public contract" <Info> note that indirectly covers the first three). The Internal request fields section and the cubeCredentials / agentId / context explanations referenced in the earlier review comment on this PR are not in the committed diff — likely got dropped between commits or squashed away. Worth double-checking whether that content was intentionally removed in favor of the shorter "complete public contract" note, or whether it should be restored.

Minor optional nits (non-blocking):

• L588: The two-column table header underline uses different dash counts (|-----------|------------------------|) — cosmetic only, GitHub/Mintlify render fine either way.
• L583: "documented in detail below" — the linked #cubemeta and #cubesqlapi sections are ~40 and ~140 lines further down; consider "documented in detail later in this section" for clarity, though "below" is fine.
• The table lumps cubeSqlApi and cubeSqlApiWithChart into one row with a compact WithChart note — that reads well, but if a reader searches for cubeSqlApiWithChart specifically the entry is still discoverable via the literal string. No change needed.

No correctness, security, or link-integrity issues.

• Branch: [alex/cub-3108-document-the-stream-chat-state-endpoint-better](https://github.com/cube-js/cube/tree/alex/cub-3108-document-the-stream-chat-state-endpoint-better)

[claude]

Claude finished @vasilev-alex's task in 51s —— View job

---

Code Review

LGTM — docs-only +47/-0; no issues found (expand for details)

• Fetch diff (git show 3c40d99)
• Verify anchors, links, and Mintlify component usage
• Check against docs-mintlify/CLAUDE.md conventions
• Deduplicate against prior review threads (none exist)

Verdict: LGTM. Clean docs-only change to docs-mintlify/reference/embed-apis/chat-api.mdx:

1. L280–286 — new <Info> block stating the documented request body fields are the complete public contract; any other fields are ignored/resolved server-side.
2. L571–608 — new #### Tool names subsection under Tool Call Handling explaining toolCall.name is an open, evolving set, with a table of common tool names and their meanings.

Anchor & link check:

• [cubeMeta](#cubemeta) → matches #### cubeMeta at L627 ✅
• [cubeSqlApi](#cubesqlapi) → matches #### cubeSqlApi at L724 ✅
• /admin/ai/certified-queries and /admin/ai/skills — root-relative as required ✅

Conventions:

• Uses Mintlify <Info> component with blank lines inside the tags ✅
• Heading depth (####) is consistent with the surrounding "Tool Call Handling" section ✅
• No H1; frontmatter untouched ✅

Content alignment with PR description:

• "Tool names" section states the set is open and evolving, advises graceful handling of unknown names, and provides a table of common names — matches PR body ✅
• <Info> note that documented fields are the complete public contract — matches PR body ✅

Minor optional nits (non-blocking):

• L588 table header underline uses a shorter dash count on the second column (|------------------------|) than the visual column width — cosmetic only; renders fine.
• The row combining cubeSqlApi and cubeSqlApiWithChart reads well and both names remain grep-discoverable as literal strings.

No correctness, security, or link-integrity issues.

• Branch: alex/cub-3108-document-the-stream-chat-state-endpoint-better •

[claude]

Claude finished @vasilev-alex's task in 45s —— View job

---

Code Review

LGTM — docs-only +53/-0; no blocking issues (expand for details)

• Fetch diff (git show 6615a21)
• Verify anchors, links, and Mintlify component usage
• Check against docs-mintlify/CLAUDE.md conventions
• Content alignment with PR description

Verdict: LGTM. Clean docs-only change to docs-mintlify/reference/embed-apis/chat-api.mdx:

1. L280–286 — new <Info> block noting the documented request body fields are the complete public contract of the Chat API; any other fields are ignored/resolved server-side.
2. L571–615 — new #### Tool names subsection under Tool Call Handling, explaining toolCall.name is an open, evolving set and providing a table of common tool names with what each does and when it's available.

Anchor & link check:

• [cubeMeta](#cubemeta) → matches #### cubeMeta further down ✅
• [cubeSqlApi](#cubesqlapi) → matches #### cubeSqlApi further down ✅
• /admin/ai/certified-queries and /admin/ai/skills — root-relative as required ✅

Conventions:

• <Info> component uses blank lines inside the tags ✅
• Heading depth (####) is consistent with the surrounding "Tool Call Handling" section ✅
• No H1; frontmatter untouched ✅

Content alignment with PR description: matches — "Tool names" section states the set is open and evolving, advises graceful handling, and lists common names; <Info> note that documented fields are the complete public contract is present.

Minor optional nits (non-blocking):

• L588 table header underline uses a shorter dash count on the second column than the rendered column width — cosmetic only; GitHub/Mintlify render fine.
• The row combining cubeSqlApi and cubeSqlApiWithChart reads well and both names remain grep-discoverable as literal strings.
• The "Available" column mixes "Always" with prose conditions ("User can create reports and dashboards", "Chatting with a dashboard", "…enabled for the agent"). Consider a follow-up to normalize the condition phrasing (e.g., always "when X" or always a short capability tag) if you want the column to scan as a strict enum.

No correctness, security, or link-integrity issues.

• Branch: alex/cub-3108-document-the-stream-chat-state-endpoint-better •

[claude]

Claude finished @vasilev-alex's task in 59s —— View job

---

Code Review

Verdict: LGTM. Docs-only +56/−0; no blocking issues.

Details

• Fetch diff (git show 592cb03)
• Verify anchors, links, and Mintlify component usage
• Check against docs-mintlify/CLAUDE.md conventions
• Content alignment with PR description

Two additions to docs-mintlify/reference/embed-apis/chat-api.mdx:

1. L280–286 — new <Info> block noting the documented request body fields are the complete public contract of the Chat API; anything else is ignored/resolved server-side.
2. L571–615 — new #### Tool names subsection under Tool Call Handling: the tool set is open and evolving, clients should handle unknown names gracefully, and a table lists common tool names with what each does and when it's available.

Anchor & link check:

• [cubeMeta](#cubemeta) → #### cubeMeta at L636 ✅
• [cubeSqlApi](#cubesqlapi) → #### cubeSqlApi at L733 ✅
• /admin/ai/certified-queries, /admin/ai/skills — root-relative ✅

Conventions:

• <Info> component uses blank lines inside the tags ✅
• #### heading depth is consistent with the surrounding "Tool Call Handling" section ✅
• No H1; frontmatter untouched ✅

Content alignment with PR description: matches — the "Tool names" section describes the open/evolving nature, advises graceful handling, and includes the table; the <Info> note about the complete public contract is present.

Minor optional nits (non-blocking):

• L588 table header underline uses a shorter dash count than the rendered column width — cosmetic only, renders fine on GitHub/Mintlify.
• The Available column mixes Always with prose conditions (User can create reports and dashboards, Web access enabled for the agent, etc.). Consider a follow-up to normalize (e.g., always "when X" or a short capability tag) if you want it to scan as a strict enum.
• The row combining cubeSqlApi and cubeSqlApiWithChart reads well and both names remain literal-grep-discoverable.

No correctness, security, or link-integrity issues.

• Branch: alex/cub-3108-document-the-stream-chat-state-endpoint-better •