Tool Recommendation
Tool Recommendation lets an agent describe a task and get back only the tools that fit it, instead of holding every tool on a gateway in its context. This page is for agent developers and platform operators who run gateways with many tools. It explains what an client gets when Tool Recommendation is on, how the finds and calls , and what decides the quality of the results. Read it before you turn Tool Recommendation on for a gateway.
Why it exists
An client normally lists every tool on a gateway and passes all of their names, descriptions, and input schemas to the model. A gateway that federates a handful of can expose hundreds of tools. At that size the tool definitions consume a large share of the window, and the model picks the wrong more often because it has too many near-matches to choose from.
With Tool Recommendation on, the gateway lists a small, fixed set of Arcade tools. The asks for the it needs when it needs them, and Arcade returns the few that match.
What an MCP client gets
When Recommendation is on for a gateway, the gateway’s tool list contains only these Arcade tools:
| Tool | What it does |
|---|---|
Arcade.SelectTools | Takes one or more task descriptions and returns the tools that match each task most closely, with their full input schemas. |
Arcade.UseTool | Runs a tool by name with the inputs you pass. |
Arcade.ListApps | Lists the apps the caller can act on and whether the caller has connected each one. |
The list spells these names with an underscore separator, for example Arcade_SelectTools. Arcade accepts either form in a tool call.
The gateway also serves Arcade.SearchTools, a keyword search over the same tools. It does not appear in the tool list, but an can call it by name. See Selection and search.
The tool list doesn’t grow as the works. that Arcade.SelectTools returns are not added to it, so listing tools again later returns the same Arcade tools. The agent gets each recommended tool’s input schema in the Arcade.SelectTools response and runs the tool through Arcade.UseTool.
How an agent finds and calls a tool
The works in two steps.
First, it calls Arcade.SelectTools with the tasks it wants to complete. Each entry in tasks describes one separate action:
{
"tasks": ["send a Slack message to a channel", "create a GitHub issue"],
"context": "The user is triaging a production incident"
}Arcade returns up to five tools per task, ranked by how well they match. Each result includes the ’s name, description, and input schema, plus a query_id for the whole request.
When a task gets no , its result includes an empty_reason. The uses it to decide whether to retry:
no_match: Arcade finished the lookup and found no tool the may use for that task. Retrying the same task returns the same answer.unavailable: The lookup for that task didn’t complete. Retrying may succeed.
Second, the calls Arcade.UseTool with the it picked and that tool’s own arguments nested inside inputs:
{
"tool_name": "Slack.SendMessage",
"inputs": {
"channel_name": "incidents",
"message": "Investigating elevated error rates on checkout."
},
"query_id": "the query_id returned by Arcade.SelectTools"
}query_id is optional. Arcade uses it to connect the to the recommendation that surfaced it.
The tool descriptions that Arcade serves tell the model how to use this flow, so most need no extra prompting.
Selection and search
Arcade offers two ways to find , and they answer different questions.
Arcade.SelectTools | Arcade.SearchTools | |
|---|---|---|
| Name of the capability | Tool Recommendation | Tool Search |
| How it matches | Semantic. It compares the meaning of a task with the meaning of each tool. | Keyword. It ranks tools by the words they share with the query, using BM25. |
| Input | One or more task descriptions | A keyword query and an optional result count (top_k, default 10, maximum 25) |
| Returns | Up to five tools per task, with full input schemas | Tool names and descriptions |
| Use it to | Find the tool to call for a specific task | Browse what tools exist, or look up a tool whose name you already know |
Semantic selection finds a tool even when the task shares no words with the tool’s name, for example “let the team know the deploy finished” matching a Slack tool. Keyword search is more predictable when the already knows a product or name.
What Arcade can recommend
Recommendation only works within the tools the gateway already allows. Arcade.SelectTools and Arcade.SearchTools return only tools that are in the gateway’s Allowed Tools list, and Arcade.UseTool runs only those tools. Turning on Tool Recommendation never gives an access to a tool the gateway does not allow.
Arcade.UseTool decides whether to run a from the gateway’s allowed list and your governance rules, not from what Arcade.SelectTools returned earlier. If a tool is on the allowed list, an can run it through Arcade.UseTool even if Arcade.SelectTools never returned it.
Contextual Access rules still apply. A that your access rules hide from a is not recommended to that user, and your access rules still govern every call through Arcade.UseTool.
How it works with MCP clients
Tool Recommendation runs inside the gateway and speaks standard . The Arcade tools are ordinary MCP tools, so any MCP client that can connect to an Arcade can use them. You don’t need an Arcade SDK, a client plugin, or code changes in your .
What makes recommendations good
Arcade matches a task against each ’s name and description. The input parameters are not part of the match, and Arcade reads only the first line of each description.
That makes descriptions the main factor you control. A tool with a vague or empty first line is hard to recommend, however useful the tool is. When you build your own tools or register a remote MCP server:
- Start each description with one sentence that says what the does and to what, for example “Send a message to a Slack channel or .”
- Name the service or object the acts on. “Create an issue in a GitHub repository” matches more tasks than “Create an item.”
- Give that do different jobs descriptions that read differently. Two tools whose first lines are nearly identical compete for the same tasks.