[PLT-1116] docs: add Tool Recommendation section under MCP Gateways

[itsthatriver]

Summary

Adds a new Tool Recommendation section under Operate → Governance → MCP Gateways, with three customer-facing pages and a link from the MCP Gateways overview. Tracks PLT-1116.

Page	Path	Covers
How it works	/operate/governance/mcp-gateways/tool-recommendation	The Arcade tools an MCP client gets (SelectTools, UseTool, ListApps; SearchTools callable but unlisted), the select-then-use flow, semantic selection vs BM25 keyword search, allowlist and Contextual Access scoping, MCP-native (no SDK changes), and why tool descriptions drive quality
Configure	.../tool-recommendation/configure	Dashboard toggle (Tool Recommendations card in Select apps), PATCH API, the PUT reset pitfall, allowlist interaction, per-connection ?tool_recommendation=false / ?arcade_tools=false opt-outs, what callers get when it's off, and a check-that-it-works list
When not to use it	.../tool-recommendation/limitations	Small gateways (< ~10 tools), fixed-workflow agents, thin descriptions, plus limits: remote MCP server tool lists are read at registration and not refreshed on a schedule, background indexing delay, five results per task, allowed-tools-only

Naming

"Tool Recommendation" is the product name throughout. "Tool Search" appears only as the name of the BM25 keyword leg (Arcade.SearchTools).

Accuracy notes for reviewers

Every behavior claim was checked against the monorepo code at 7a804fcf35 (engine mcp/metatools, arcadetools/definitions.go, api/schemas/crud_gateway.go, mcp/gatewayoptions; dashboard mcp-gateways form; Condex embedding templates). A few points worth a second look:

• Customer-only content. There are no database steps, no internal flag names, and no staging URLs. When the org isn't entitled, the page says the toggle doesn't appear and points to Contact us.
• Remote MCP server tool lists are described as not re-read on a schedule. PLT-3580, which would have added a refresh cadence, is canceled, so this limit stands. The tool list is re-read on registration, on an update to the registration, and when someone authorizes an OAuth server (CatalogRefresher, GRO-377).
• Five results per task and "first line of the description" reflect the current hardcoded topK and the default Condex embedding config. Both could change later.
• ?tool_recommendation / ?arcade_tools URL parameters are documented for the first time here.
• I left out the "in-app prompt when a gateway has under ten tools" idea from the ticket. It's still an open product decision.

What changed in this revision

Rebased onto docs main (258b9547). Only the generated public/llms.txt header conflicted. I took main's header and kept the three new index entries.

Fix	Decision
The overview no longer says recommended tools are added to the tool list. On a Tool Recommendation gateway, tools/list returns only the Arcade tools, before and after SelectTools. Matches monorepo#5240.	PLT-4127
UseTool is described as admitting a tool by the allowed list plus governance rules (Contextual Access), not by prior selection. The configure page's check-it-works step says the list stays fixed.	PLT-4127
The overview documents the per-task empty_reason: no_match (retrying won't help) or unavailable (retrying may help). No page says "degraded". Matches monorepo#4459.	PLT-3553
No GET /v1/apps / REST ListApps content. These pages don't cover the tools REST surface, and #5159 is still in review.	PLT-3500
The limitations page names OAuth authorization as a third re-read trigger. The no-cadence claim stays because PLT-3580 is canceled. Naming, customer-only content, and the few-tools, fixed-workflow, and thin-descriptions cases were rechecked and unchanged.	PLT-1116

Merge order: the empty_reason paragraph and the fixed-tool-list wording describe monorepo#4459 and #5240, which are both open. Ship this page after they deploy, or the docs will run ahead of the product for a while.

Verification

• vale 3.14.2 (CI's pinned version), with vale sync, run on each changed page as Markdown (vale --ext=.md --output=line < page.mdx). The two findings this revision introduced (Anthropomorphism, Passive) are fixed. What's left is expected: Google.Headings on the product name "Tool Recommendation", and Google.Semicolons on the MDX import line, which only appears because MDX is linted as Markdown (the MCP Gateways overview on main gets the same flag). The lines added to the MCP Gateways overview have no findings.
• pnpm install --frozen-lockfile && pnpm run lint && pnpm run typecheck: all pass.
• Not re-run in this revision: pnpm build. The nav and _meta.tsx are unchanged since the earlier build.

~ Δ Delta, downstream of River

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes with no runtime, API, or application code modifications.

Overview
Adds customer-facing Tool Recommendation documentation under Operate → Governance → MCP Gateways, with navigation updates and a new overview link on the MCP Gateways page.

The new section includes an overview (select-then-use flow via Arcade.SelectTools / Arcade.UseTool, semantic vs keyword search, allowlist and Contextual Access), a Configure page (dashboard toggle, tool_filter.discovery.enabled via PATCH, PUT pitfalls, per-connection URL opt-outs), and When not to use it (small gateways, fixed workflows, description quality, operational limits). public/llms.txt is updated so agents can discover the new routes.

^{Reviewed by Cursor Bugbot for commit 657034f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Closes PLT-1116

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 8, 2026 12:17am UTC