---
title: "The tool catalog with each tool's tier, availability and per-provider schema cost"
method: GET
path: "/v1/tools/catalog"
tags: ["Tools"]
---

# The tool catalog with each tool's tier, availability and per-provider schema cost

`GET /v1/tools/catalog`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/tools/catalog`
- Auth: HTTP bearer

Returns every native tool this build offers and every federated tool from a
connected MCP server, each with its tier, its availability for the current
license and governance overlay, its annotations and its estimated schema
token cost per chat provider. DEBUG builds add a `debug` object with
ToolGate's runtime state.

## Response `200`

Catalog snapshot

- ToolCatalogSnapshot
  - `version` integer, required: Snapshot format version (1).
  - `tool_count` integer, required: Rows in `tools`, native and federated.
  - `native_tool_count` integer, required
  - `federated_tool_count` integer, required
  - `default_provider` string, required: The provider whose serialization budgets are summed against (`openai`, the conservative worst case).
  - `per_tool_soft_cap_tokens` integer, required
  - `providers` string[], required: The chat providers each row's `tokenCost` is keyed by.
  - `current_tier` string, required: The license tier `availability` was composed against.
  - `tools` ToolCatalogRow[], required: Every native tool not withheld from this build, then every federated tool from a connected MCP server.
    - `name` string, required
    - `title` string, required: The catalog title; a federated row's upstream raw name.
    - `category` string, required: The native category, or `federated`.
    - `tier` string, required: The tier the tool requires; `free` for a federated row.
    - `availability` 'available' | 'tier_locked' | 'policy_blocked', required
    - `readOnly` boolean, required
    - `destructive` boolean, required
    - `openWorld` boolean, required
    - `tokenCost` object, required: Estimated schema tokens per provider in `providers`.
    - `tierDefault` 'allow' | 'ask' | 'deny', required: Kept for the clients that read it; always `allow`.
    - `source` 'native' | 'federated', required
    - `server_name` string: Federated rows only.
    - `raw_name` string: Federated rows only.
    - `description` string: Federated rows only. The server's own description, unneutralized, for a person deciding whether to allow it.
  - `debug` object: DEBUG builds only, when ToolGate is running. ToolGate's runtime state; release builds omit the key.
    - `mcp_tools` integer, required: Native tools in the catalog.
    - `client_tools` integer, required: Distinct session-registered client tool names.
    - `indexed_catalog_size` integer, required: Tool names embedded in the retrieval index.
    - `bundles` string[], required

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)