docs: add Tool Recommendation page and gateway setup steps

app/en/get-started/quickstarts/call-tool-client/page.mdx

@@ -24,7 +24,7 @@ export const MCP_GATEWAY_URL_LIGHT_HEIGHT = 498;
 
 # Call a tool in your IDE/MCP Client
 
-Tools enable your AI agents to perform actions on your behalf. For specific workflows and use cases, this may involve calling tools from multiple MCP servers. Arcade facilitates this by allowing you to create MCP Gateways to federate the tools from multiple MCP servers into a single collection for convenient management, control, and access. For example, if your agent specializes in solving specific tickets in Linear, you may want to use tools from the GitHub, Slack and Linear servers in your agent. These add up to 88 tools, which could be overwhelming for an LLM to use effectively. What you want is to get from these servers only the tools that matter for your agent. An MCP Gateway allows you to do just that: pick only the tools required for this workflow, and you can connect it to any MCP client, making it possible to port your agent to multiple platforms and IDEs, and even share it with other users.
+Tools enable your AI agents to perform actions on your behalf. For specific workflows and use cases, this may involve calling tools from multiple MCP servers. Arcade facilitates this by allowing you to create MCP Gateways to federate the tools from multiple MCP servers into a single collection for convenient management, control, and access. For example, if your agent specializes in solving specific tickets in Linear, you may want to use tools from the GitHub, Slack and Linear servers in your agent. These add up to 88 tools, which could be overwhelming for an LLM to use effectively. An MCP Gateway lets you pick the tools for this workflow, and with [Tool Recommendation](/operate/governance/mcp-gateways/tool-recommendation) on, your agent requests only the tools each task needs instead of loading all of them up front. You can connect the gateway to any MCP client, making it possible to port your agent to multiple platforms and IDEs, and even share it with other users.
 
 <GuideOverview>
 <GuideOverview.Outcomes>
@@ -41,7 +41,7 @@ Create a coding agent using an MCP Gateway to call tools from multiple MCP serve
 
 <GuideOverview.YouWillLearn>
 
-- Create an MCP Gateway
+- Create an MCP Gateway with Tool Recommendation
 - Connect the MCP Gateway to Cursor or VS Code
 - Call tools from the MCP Gateway in your agent
 
@@ -102,10 +102,20 @@ Feel free to select any tools you want to include in your specific use case.
   height={TOOL_PICKER_DARK_HEIGHT / IMAGE_SCALE_FACTOR}
 />
 
-Once you've selected the tools you want to include in the gateway, click the "Use N tools" button in the tool picker, and then click the "Create MCP Gateway" button to create the gateway.
+Once you've selected the tools you want to include in the gateway, click the "Use N tools" button in the tool picker.
+
+### Keep Tool Recommendations on
+
+**Leave the "Tool Recommendations" checkbox checked.** It's on by default for new gateways. With Tool Recommendations on, the gateway doesn't send every tool definition to your agent. Instead, the agent describes each task and Arcade returns only the tools that task needs, so a large tool set doesn't fill the model's context window. See [Tool Recommendation](/operate/governance/mcp-gateways/tool-recommendation) for how it works.
+
+Click the "Create MCP Gateway" button to create the gateway.
 
 <Callout type="info">
-  You can select as many tools for your MCP Gateway as you want, but be mindful of how the MCP clients will handle the large number of tools. Some clients may not handle a large number of tools well, and may consume a significant portion of the LLM's context window. We recommend keeping the number of tools in a single MCP Gateway below 80.```
+  If you turn Tool Recommendations off, the gateway lists every selected tool to
+  your agent on every request. Some clients don't handle a large number of tools
+  well, and the definitions can consume a significant portion of the LLM's
+  context window. With Tool Recommendations off, keep the number of tools in a
+  single MCP Gateway below 80.
 </Callout>
 
 ### Connect the MCP Gateway to an MCP client
@@ -141,13 +151,14 @@ Select the MCP client you want to use to read the instructions to connect to the
 1. Open your IDE's chat pane.
 1. Ask the agent to do something! For example, "Check the latest linear issue assigned to me. Then, create a new GitHub branch, implement the fix, and add tests. If all the tests pass, create a pull request and assign it to me."
 
-As you interact with the agent, it will call the tools from the MCP Gateway. Your agent should prompt you to visit links to authorize access to Linear and GitHub. After this, it will start using tools to carry out the task! Subsequent calls will not require authorization.
+As you interact with the agent, it will call the tools from the MCP Gateway. With Tool Recommendations on, you'll see the agent call `Arcade_SelectTools` to find the Linear and GitHub tools it needs, then `Arcade_UseTool` to run them. Your agent should prompt you to visit links to authorize access to Linear and GitHub. After this, it will start using tools to carry out the task! Subsequent calls will not require authorization.
 
 </Steps>
 
 ## Next Steps
 
 - Learn more about [MCP Gateways](/operate/governance/mcp-gateways).
+- Learn how [Tool Recommendation](/operate/governance/mcp-gateways/tool-recommendation) works and when to turn it off.
 - Learn how to use MCP Gateways with:
   - [Cursor](/get-started/mcp-clients/cursor)
   - [Visual Studio Code](/get-started/mcp-clients/visual-studio-code)

app/en/operate/governance/mcp-gateways/_meta.tsx

@@ -7,6 +7,9 @@ export const meta: MetaRecord = {
   "create-via-ai": {
     title: "Create via AI Assistant",
   },
+  "tool-recommendation": {
+    title: "Tool Recommendation",
+  },
 };
 
 export default meta;

app/en/operate/governance/mcp-gateways/tool-recommendation/page.mdx

@@ -0,0 +1,99 @@
+---
+title: "Tool Recommendation"
+description: "Give agents your gateway's full tool catalog by letting them request the tools each task needs"
+---
+
+import { Callout, Steps } from "nextra/components";
+
+# Tool Recommendation
+
+Tool Recommendation lets an agent reach every tool on an MCP Gateway without loading all of them up front. Instead of listing each tool definition, the gateway gives the agent a small, fixed set of tools. The agent describes what it needs to do, Arcade returns the tools that fit, and the agent runs them under the end user's own authorization.
+
+This page is for platform operators who configure MCP Gateways, and for agent developers who want to understand what their agent sees when Tool Recommendation is on.
+
+## Why use Tool Recommendation
+
+An agent can only call the tools whose definitions it has. With a static tool list, the MCP client sends every definition on every request, so each tool you add makes every request larger. That forces a trade-off:
+
+- **A short list** keeps requests small but limits the agent to the tasks you anticipated. Every new need becomes a configuration change.
+- **A long list** widens what the agent can do, but raises the cost of every request, and models pick the wrong tool more often as the list grows.
+
+Arcade's catalog has over 8,000 tools, far more than fits in any model's context window. Tool Recommendation removes the trade-off: the agent can reach every tool the gateway allows, and the definitions it carries stay small no matter how large the catalog grows.
+
+## How it works
+
+When Tool Recommendation is on, a gateway lists these tools instead of its allowed tools:
+
+| Tool | What it does |
+| --- | --- |
+| `Arcade_SelectTools` | Takes one or more task descriptions in plain language and returns, for each one, a ranked list of matching tools with their full input schemas. |
+| `Arcade_UseTool` | Runs a tool returned by `Arcade_SelectTools`, with the inputs the agent supplies. |
+| `Arcade_ListApps` | Reports which apps sit behind the gateway and whether the end user has connected each one. |
+
+A typical turn looks like this:
+
+<Steps>
+
+### The agent describes the task
+
+The agent calls `Arcade_SelectTools` with a description such as `find the open Linear issue assigned to me`. It can pass several unrelated tasks in one call.
+
+### Arcade recommends tools
+
+Arcade ranks the tools the gateway allows for that end user and returns the best matches, each with its description and input schema. Ranking runs in two stages: a first stage retrieves candidate tools, and a second stage orders them by reading the task and each tool together.
+
+### The agent runs a tool
+
+The agent calls `Arcade_UseTool` with a returned tool's name and inputs, and passes along the `query_id` from the `Arcade_SelectTools` response. Arcade runs the tool and returns the result.
+
+</Steps>
+
+Tool Recommendation doesn't require training on your tools. Arcade indexes tools as they're added, updated, or removed, so new tools, including tools your organization registers, become recommendable without any redeploy.
+
+## Governance still applies
+
+Tool Recommendation runs inside Arcade's runtime, so it never widens what an agent can do:
+
+- **Allowlist.** `Arcade_SelectTools` only ranks tools on the gateway's allowlist. A tool you remove from the allowlist stops appearing in later results.
+- **Access hooks.** A [Contextual Access](/operate/governance/contextual-access) access hook that hides a tool from an end user also hides it from that user's recommendations.
+- **Execution hooks.** A pre-execution hook that blocks a tool call blocks it the same way when the call comes through `Arcade_UseTool`.
+- **End-user authorization.** `Arcade_UseTool` runs each tool as the end user. Provider credentials stay with Arcade and never enter the agent's context. If a tool needs consent the user hasn't given, the agent receives an authorization link instead of a result, and can repeat the call once the user approves.
+
+## Turn Tool Recommendation on or off
+
+**Per gateway.** The gateway form in the [MCP Gateways dashboard](https://api.arcade.dev/dashboard/mcp-gateways) has a **Tool Recommendations** checkbox. Through the API, this is the gateway's `tool_filter.discovery.enabled` field. The setting applies only to that gateway.
+
+- **New gateways** have Tool Recommendations checked by default.
+- **Existing gateways** created before Tool Recommendation was available keep listing their tools as before. Open the gateway, check **Tool Recommendations**, and save to turn it on.
+
+<Callout type="info">
+  The **Tool Recommendations** checkbox appears only when Tool Recommendation is
+  available to your organization.
+</Callout>
+
+**Per connection.** Add a query parameter to the gateway URL in an MCP client's configuration to turn Tool Recommendation off for that connection only. The client then receives the gateway's full tool list. The gateway setting doesn't change.
+
+```text
+https://api.arcade.dev/mcp/{YOUR-GATEWAY-SLUG}?tool_recommendation=false
+```
+
+## When to use it
+
+Tool Recommendation pays off as the number of tools grows and when agents carry out multi-step work. Each `Arcade_SelectTools` call adds a round trip, so cost and latency depend on how often the agent searches:
+
+- **Use Tool Recommendation** when a gateway has many tools, when you don't know in advance which tools users will need, or when agents chain several tool calls to finish a task.
+- **Use a static list** for a small, stable set of tools, especially when most tasks need only one tool. With only a handful of tools, listing them directly sends less than a search would.
+
+Cost also depends on the MCP client. Recommended tools join the session's tool list as the agent requests them, and clients differ in how they handle a tool list that grows during a session. Clients that defer loading tool definitions, such as Claude Code with tool search enabled, handle this efficiently.
+
+## Related tools and pages
+
+- The gateway's [Private Registry](/operate/governance/private-registry) lists every tool the gateway allows, whether or not Tool Recommendation is on.
+- `Arcade_ListApps` and the [Registry tools](/operate/governance/private-registry#capability-requests) stay available whether Tool Recommendation is on or off.
+- To hide all of Arcade's agent tools from one connection, add `arcade_tools=false` to the gateway URL.
+
+## Next steps
+
+- [Create an MCP Gateway](/operate/governance/mcp-gateways/create-via-dashboard)
+- [Call a tool in your IDE or MCP client](/get-started/quickstarts/call-tool-client)
+- [Connect a gateway to your MCP client](/get-started/mcp-clients)

public/llms.txt

@@ -1,4 +1,4 @@
-<!-- git-sha: ba8ae410f0f64ade27b2780615eb2b98d10dafab generation-date: 2026-10-08T15:09:54.189Z -->
+<!-- git-sha: b380dcea11b9f8ea6ad3d7a4a25cec99f6d5f698 generation-date: 2026-10-09T22:27:50.174Z -->
 
 # Arcade
 
@@ -174,6 +174,7 @@ Arcade docs serve two audiences. Start with the path that matches your goal:
 - [The Arcade Registry](https://docs.arcade.dev/en/resources/registry-early-access): The Arcade Registry documentation provides an overview of a platform where developers can share and monetize their tools for agentic applications, similar to HuggingFace or Pypi. It explains how the registry integrates runtime metrics and user feedback to enhance tool development and usage
 - [Tool error handling](https://docs.arcade.dev/en/build/tool-calling/error-handling): This page teaches users how to handle errors when calling tools through Arcade's client libraries, covering structured error types, handling examples in Python/JavaScript/Java, and best practices for robust error management. It explains Arcade's error hierarchy system and shows users how to debug failed tool calls using Arcade's recorded execution history.
 - [Tool executions](https://docs.arcade.dev/en/operate/governance/tool-executions): Arcade records every tool execution in a project, capturing which tool ran, for which user, when, and its outcome, with inputs and outputs restricted to project admins for security. This page helps developers debug failed tool runs by reviewing exact inputs and outputs, and helps platform operators monitor tool usage and ensure compliance across their projects.
+- [Tool Recommendation](https://docs.arcade.dev/en/operate/governance/mcp-gateways/tool-recommendation): Tool Recommendation enables agents to access a large tool catalog dynamically without loading all tool definitions upfront by letting them request only the tools needed for each task. The system uses three special tools—`Arcade_SelectTools` to find matching tools, `Arcade_UseTool` to execute them, and `Arcade_ListApps` to check app connections—while maintaining full governance controls like allowlists and access hooks. This approach eliminates the trade-off between keeping requests small and giving agents broad capability, allowing access to thousands of tools without increasing context size.
 - [Tools](https://docs.arcade.dev/en/resources/tools): This documentation page provides an overview of Arcade's ecosystem for AI tools, enabling users to explore a catalog of pre-built integrations, create custom tools, and contribute their own tools to the community. It outlines the benefits of using Arcade tools, such as built
 - [Types of Tools](https://docs.arcade.dev/en/build/create-tools/improve/types-of-tools): Arcade offers two types of tools—Optimized and Unoptimized—that differ in their design approach but work identically through the same interface. Optimized tools are carefully designed to match AI chat interfaces and improve reliability by handling complex workflows automatically, while Unoptimized tools mirror original HTTP endpoints and require more careful evaluation before production use. Both types can be used seamlessly together in Arcade's Dashboard and SDK clients.
 - [Understanding `Context` and tools](https://docs.arcade.dev/en/build/create-tools/tool-basics/runtime-data-access): The `Context` class provides tools with access to both runtime capabilities and tool-specific data, such as OAuth tokens, secrets, and user information, as well as features like logging, LLM sampling, user elicitation, and progress reporting. This guide explains how to use the `Context` object that is automatically passed to tools by the MCP server to securely access authentication credentials and leverage runtime features during tool execution.