---
title: Tool Search (public)
description: Action Gateway tool search discovers relevant catalog tools and their schemas without loading the entire catalog into an agent's context.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-search/
last_updated: "2026-09-21"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# Tool Search (public)

Action Gateway gives applications and AI agents governed access to tens of thousands of tools through a managed MCP endpoint or SDK. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases of Action Gateway with Harness Runtime.

Action Gateway’s `action_search` meta tool discovers catalog tools from a description of the task you want to complete. It returns tool definitions rather than executing the tools, so an agent can inspect the required inputs before making a call.

Search ranks tools by relevance to the described task and narrows the results to tools the session can access. The agent receives a limited set of candidate tools and their schemas instead of the full catalog. This reduces the definitions it needs to evaluate and the model context spent on tools unrelated to the task.

Tool search is included in [Action Gateway pricing](https://docs.digitalocean.com/products/managed-agents/action-gateway/details/pricing/index.html.md). Calls to `action_search` do not incur a tool-call charge.

## Search Queries

A search request contains a `queries` array with one to five use cases. Describe the action and intended outcome in `use_case`, including the provider when it matters. Separate independent actions into separate queries.

For example, pass the following arguments to `action_search` to find tools for listing Droplet sizes:

```json
{
  "queries": [
    {
      "use_case": "List available DigitalOcean Droplet sizes"
    }
  ],
  "limit": 5
}
```

Optional `providers` and `tags` filters narrow every query in the request. The `limit` field caps the number of returned tools per query.

Use `known_fields` for short, structured workflow inputs that are already known. It accepts a string of comma-separated `key:value` pairs, not an object or array. Do not put credentials or long message bodies into search queries.

## Search Results and Permissions

Results are grouped by query. Inspect the returned tool name, version, description, and input schema rather than guessing a tool’s name or arguments. Pass the chosen tool to [action_invoke](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/invoke-tool/index.html.md) or use it from [action_code](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/code-execution-tool/index.html.md).

Search respects the session’s tool selection and filters out tools that have no permitted invocation. A result is not an authorization decision for a particular set of arguments. The gateway evaluates the policy again when the tool runs, and the tool may require approval or a provider connection.

An empty result can mean that no catalog tool matches the query or that the session cannot access a matching tool. Refine the query or check the [session’s tool selection and policy](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-policies/index.html.md). Pure computation can use `action_code` without a catalog search.

## Search and Preloading

Search discovers tools as needed and adds only the returned definitions to the agent’s context. Use it when the task could require tools you have not chosen in advance. Describe the intended outcome and limit results to keep discovery focused.

[Preloading](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/preloading-tools/index.html.md) instead adds selected tool definitions directly to the session’s MCP tool list at creation. The agent can use these tools without a discovery call, but their definitions consume context even when the task does not need them. Preload a small set of known, frequently used tools and use search for the rest. Neither mechanism expands the session’s tool permissions.