---
title: Tool Versions (public)
description: Action Gateway tool versions let you pin a tool to a released version, review what changed between releases, and see when a newer version exists.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-versions/
last_updated: "2026-11-18"
---

> **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 Versions (public)

Action Gateway connects applications and AI agents to tools through a managed MCP endpoint or SDK, with the accounts and permissions you choose. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/action-gateway/details/what-you-can-build/index.html.md) for standalone agent examples.

Each Action Gateway catalog tool has numbered versions, such as `v16` and `v17`. A new version is released when the tool’s definition changes, for example when it gains an input property or requires another OAuth scope. Released versions don’t change, and you can keep calling an older one after newer versions are released.

## Which Version a Call Uses

A call that names a tool without a version, such as `supabase_list_organizations`, always runs the latest release. It picks up new versions as soon as they are released, including changes that can break your integration.

To keep calling one version, pin it by name in `<tool>@<version>` form, such as `supabase_list_organizations@v16`. `v16` and `16` are equivalent. Pin a version in an endpoint version’s tool selection or [preloads](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/preloading-tools/index.html.md), in a [Toolbelt](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/toolbelts/index.html.md) member, or with the `version` field of an [Invoke Tool](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/invoke-tool/index.html.md) call.

A pinned version stays available after newer versions are released. DigitalOcean removes a released version only in exceptional cases, such as a legal requirement.

Only versions that appear in the version list can be pinned. Versions that were replaced before version history was recorded on November 2, 2026, are not listed and can’t be pinned.

## Learn That a Newer Version Exists

When a call pinned to an older version succeeds, the result includes `_meta.latest_version` with the latest release:

```json
{
  "_meta": {
    "latest_version": "v17"
  }
}
```

The key is omitted when the call doesn’t pin a version or pins the latest one. It’s also omitted when the call returns no result, or when Action Gateway can’t look up the latest release, so a missing key doesn’t guarantee you’re on the latest version.

Use it to decide when to review a newer version. Calling the pinned version still works, and the result is unchanged.

## Review What Changed

List a tool’s released versions with the [List Tool Versions](https://docs.digitalocean.com/reference/api/reference/action-gateway/index.html.md) API operation, `GET /v2/action-gateway/tools/{tool_slug}/versions`. Each version is compared with the one released before it:

```bash
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/action-gateway/tools/supabase_list_organizations/versions"
```

Versions are listed newest first, 20 per page by default, up to 100 with `page_size`. To read older versions, pass the response’s `next_page_token` as `page_token`. Each version reports its `previous_version`, a `breaking` flag, and its `changes`. A change has a `type`, the `path` of the input or output property, any `values` involved, and its own `breaking` flag.

A change is breaking when a call that worked against the previous version can fail against this one. Examples are a new required input property, an input that no longer accepts a type it used to, and added required OAuth scopes. A connection authorized before the new scopes were required must be reauthorized. Review breaking changes before you move a pin or rely on the latest release.

The comparison covers input schemas, output schemas, and required scopes. It doesn’t cover descriptions, titles, or examples. Tools on your team’s MCP servers have no version history and aren’t listed.

## Move to a Newer Version

Moving a pin is a configuration change. Publish a complete new endpoint version, or a new Toolbelt version, that pins the newer tool version, and test it before you move production traffic. Existing endpoint versions keep calling the version they pinned.

If you use [output views](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/add-tool-output-view/index.html.md), check that each view still matches the newer version’s output.