---
title: Invoke Tool (public)
description: Action Gateway invokes named catalog tools with validated arguments and returns an outcome for each call.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/invoke-tool/
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).

# Invoke Tool (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_invoke` meta tool runs one or more tools using the current session’s permissions and provider connections. Use [Tool Search](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-search/index.html.md) to find the tool names and input schemas, then pass the calls you want to run to `action_invoke`.

## Tool Calls

The `tools` array contains the calls to run. Each entry names a `tool`, supplies its `arguments`, and can specify a `version`. Use the name and argument structure returned by discovery. The tool’s advertised input schema specifies the batch limit.

A [Toolbelt](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/toolbelts/index.html.md) groups tools but is not itself an invocable tool. Call its members by their individual names. A version-pinned session selection permits only the selected versions.

## Parallel Calls and Results

Pass multiple independent calls in one request to run them in parallel. For example, after discovering `exa_web_search`, an agent can search for VPC documentation and Spaces documentation without waiting for one search to finish before starting the other. The following arguments make both calls:

```json
{
  "tools": [
    {
      "tool": "exa_web_search",
      "arguments": {"query": "DigitalOcean VPC documentation"}
    },
    {
      "tool": "exa_web_search",
      "arguments": {"query": "DigitalOcean Spaces documentation"}
    }
  ]
}
```

Both searches must be allowed by the session. Exa requires a positive prepaid balance and has [additional usage charges](https://docs.digitalocean.com/products/managed-agents/action-gateway/details/pricing/index.html.md); this request makes two billable tool calls.

Calls in a single `action_invoke` request run in parallel. Their array order does not establish dependencies. Wait for an earlier result before submitting a dependent call, or use [Code Execution Tool](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/code-execution-tool/index.html.md) for a workflow that passes outputs between tools.

Each call has its own outcome. Inspect every result for success, failure, approval requirements, or connection requirements. A successful call does not mean that the other calls succeeded. A batch is not a transaction and does not roll back completed actions when another call fails.

## Policy and Credentials

The gateway validates the arguments and checks the session’s tool selection and [policy](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-policies/index.html.md) for each call, including every member of a parallel request. An `allow` decision runs the tool, `ask` requires approval, and `deny` blocks it. Permission to invoke one tool does not authorize the other calls in the batch.

Tools that need provider authorization use the session owner’s [connection](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/connections/index.html.md) for the session’s actor and the tool’s provider. The agent supplies tool arguments, not provider secrets. A permitted call can still require provider sign-in, reauthorization, or additional scopes. Follow the connection guidance for that call; approving a tool call does not authorize an external account.

An [output view](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/add-tool-output-view/index.html.md) bound to the session applies to the returned result.

When a call fails, follow its recovery guidance. Do not resubmit a write operation merely because another item in the batch failed. See [Reliable Execution](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/reliable-execution/index.html.md) for retry and idempotency limits.