Skip to Content
OperateGovernanceMCP GatewaysTool RecommendationConfigure

Configure Tool Recommendation

This page is for platform operators who manage Gateways. It shows how to turn Tool Recommendation on or off for a gateway, how it interacts with the gateway’s allowed tools, and what a caller gets when it is off. Use it when a gateway has grown past the point where an agent can hold every tool in .

Tool Recommendation is a setting on each gateway. Turning it on for one gateway does not change any other gateway in the .

Prerequisites

  • An Gateway, or permission to create one. See Create via Dashboard.
  • Recommendation available for your organization. If the Tool Recommendations option does not appear on the gateway form, it is not available for your organization yet. Contact Arcade to request access.

Turn it on in the dashboard

  1. Open the MCP Gateways dashboard .
  2. Create a gateway, or open an existing gateway and edit it.
  3. In the Select apps step, select the Recommendations card so that it shows as on.
  4. Save the gateway.

When Recommendation is available for your organization, the dashboard turns it on by default for new gateways. To turn it off, clear the Tool Recommendations card, and then save the gateway.

Turn it on with the API

Send a PATCH request to the gateway with tool_filter.discovery.enabled set to true:

Terminal
curl -X PATCH \
  "https://api.arcade.dev/v1/orgs/{org_id}/projects/{project_id}/gateways/{gateway_id}" \
  -H "Authorization: Bearer $ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_filter": {"discovery": {"enabled": true}}}'

Set enabled to false to turn it off. A PATCH that leaves out discovery keeps the current setting, and a PATCH that leaves out allowed_tools keeps the current allowed .

The gateway response reports the current setting in tool_filter.discovery.enabled. Gateways that you create through the API start with Recommendation off.

A PUT request replaces the whole gateway. If the body includes a tool_filter without a discovery block, Recommendation turns off. Include "discovery": {"enabled": true} in every PUT to a gateway that should keep it on, or use PATCH.

The gateway accepts this setting even when Recommendation is not available for your organization. In that case the setting has no effect, and the gateway behaves as if it were off.

See the Arcade API reference for the full gateway schema.

Choose which tools Arcade can recommend

Recommendation searches only the gateway’s Allowed Tools. To make a tool recommendable, add it to the gateway. To keep Arcade from ever recommending a tool or running it through the gateway, leave it out.

A few consequences follow from that:

  • Adding a large set of tools to a gateway with Tool Recommendation on does not add those tools to the model’s . The model only receives the tools the asks for.
  • Recommendation does not widen access. Arcade.UseTool refuses any tool that is not on the allowed list, with an error that starts tool not found.
  • A gateway with no allowed has nothing to recommend. Arcade.SelectTools returns an error that starts no tools are eligible for discovery.
  • A tool you add to a gateway is not recommendable the moment you save. Arcade indexes new tools in the background, so allow a short delay before you test a newly added tool. An can still run it by name through Arcade.UseTool in the meantime.

Opt out for one connection

A single client can opt out of Recommendation without changing the gateway. Add a query parameter to the gateway URL the client connects to:

URLEffect
https://api.arcade.dev/mcp/{YOUR-GATEWAY-SLUG}?tool_recommendation=falseThe tool list contains every allowed tool, as if Tool Recommendation were off.
https://api.arcade.dev/mcp/{YOUR-GATEWAY-SLUG}?arcade_tools=falseThe tool list contains every allowed tool and none of the Arcade tools, not even Arcade.ListApps.

These parameters can only narrow what a connection gets. ?tool_recommendation=true does not turn Recommendation on for a gateway that has it off.

What a caller gets when it is off

When Recommendation is off for a gateway, or is not available for your organization:

  • The list contains every allowed tool, plus Arcade.ListApps.
  • Arcade.SelectTools, Arcade.UseTool, and Arcade.SearchTools do not appear in the list. Calling any of them returns the error tool not enabled for this gateway.

If Arcade cannot confirm whether Recommendation is available for your organization, for example during a brief service disruption, the gateway keeps listing the Arcade tools. Calls to them return a message saying that Tool Recommendation is temporarily unavailable and that retrying may succeed.

Check that it works

Connect an client to the gateway and list its tools. With Recommendation on, the list contains only Arcade.SelectTools, Arcade.UseTool, and Arcade.ListApps, and it stays that way after the selects tools. Ask the agent to do something that one of your allowed tools handles, and confirm that it calls Arcade.SelectTools and then Arcade.UseTool.

If the list still shows every allowed :

  • Confirm that the Recommendations card is on for this gateway.
  • Confirm that the client URL does not include ?tool_recommendation=false or ?arcade_tools=false.
  • Reconnect the client. Some clients cache the list from an earlier session.

Next steps

Last updated on
Tool RecommendationWhen not to use it