> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # List agent tools > Lists every tool available to the tenant, aggregated across its MCP servers. Each tool carries a `ref` field — its canonical id in the form {slug}__{tool_name} — and the `mcpServerId` of the server it comes from. When setting an assistant's toolset on createAssistant, group the tools by server: one mcp_servers entry per distinct `mcpServerId`, shaped {id: , tools: [, …]}. For a server whose catalog depends on the caller, send {id: , allTools: true} with no `tools` instead — not a workaround for a server that failed to list. Put the `ref` value VERBATIM into mcp_servers[].tools. Do NOT compose the id yourself from the slug and name, and never use the display `name` — the runtime whitelist matches `ref` byte-for-byte, so any hand-built or mismatched id is silently dropped or hard-rejected. This catalog lists published tools only — unpublished (draft) tools never appear here. The catalog can also be PARTIAL: a server that did not answer is named in `failedServerSlugs` and its tools are simply missing from this 200, so a non-empty `failedServerSlugs` means "incomplete", not "that tool does not exist". ## OpenAPI ````yaml api-reference/specs/claudia/v1.json GET /v1/tenants/{tenant}/agent-tools openapi: 3.0.1 info: title: Claudia API version: 1.0.0 servers: - url: https://api.cloudhumans.com/claudia description: Production - url: https://api.cloudhumans.com/claudia/staging description: Staging security: - bearerAuth: [] tags: - name: MCP Servers description: >- The MCP servers your agents can call tools on. Registering one here is what makes its tools selectable in an agent; the credentials it needs are stored encrypted and never read back. - name: Knowledge Base Content description: Read, search and edit the content that answers your customers. - name: Content Quality description: Rewrites proposed for content that is answering your customers badly. - name: Playground description: >- Talk to one of your agents as if you were a customer, without touching a real conversation. - name: Project Settings description: >- Read and change how a ClaudIA project behaves — the settings screens of the ClaudIA app, as an API. - name: Content Improvements description: Answers Claudia proposes for questions your content does not cover yet. - name: Knowledge Bases description: The knowledge bases your account can manage. - name: Content Sources description: The sites Claudia crawls to keep a knowledge base in sync. - name: Agents description: >- The AI agents (assistants) configured for your tenant: the orchestrator (supervisor) and its specialists (react). Reads answer the same passthrough shape the platform stores; creates land as DRAFTS a human reviews and publishes in the app. - name: Agent Tools description: >- The tool catalog your agents can be given, aggregated across every MCP server registered for the tenant. This is the same catalog an assistant's mcp_servers[].tools whitelist is validated against. - name: Conversations description: >- Read access to a conversation's lean investigation summary — messages, status and resolution — and the execution trace behind one of its processed messages, without the internal processing state the hub UI's full read carries. paths: /v1/tenants/{tenant}/agent-tools: get: tags: - Agent Tools summary: List agent tools description: >- Lists every tool available to the tenant, aggregated across its MCP servers. Each tool carries a `ref` field — its canonical id in the form {slug}__{tool_name} — and the `mcpServerId` of the server it comes from. When setting an assistant's toolset on createAssistant, group the tools by server: one mcp_servers entry per distinct `mcpServerId`, shaped {id: , tools: [, …]}. For a server whose catalog depends on the caller, send {id: , allTools: true} with no `tools` instead — not a workaround for a server that failed to list. Put the `ref` value VERBATIM into mcp_servers[].tools. Do NOT compose the id yourself from the slug and name, and never use the display `name` — the runtime whitelist matches `ref` byte-for-byte, so any hand-built or mismatched id is silently dropped or hard-rejected. This catalog lists published tools only — unpublished (draft) tools never appear here. The catalog can also be PARTIAL: a server that did not answer is named in `failedServerSlugs` and its tools are simply missing from this 200, so a non-empty `failedServerSlugs` means "incomplete", not "that tool does not exist". operationId: listAgentTools parameters: - name: tenant in: path description: >- Tenant whose agents you are managing. Discover the tenants your credentials cover with `listMyClaudiaProjects`. A tenant your credentials do not cover is indistinguishable from one that does not exist. required: true schema: type: string responses: '200': description: >- The tools available to this tenant's agents, published only. Possibly partial — check `failedServerSlugs`. content: application/json: schema: $ref: '#/components/schemas/AgentToolCatalog' '400': description: The request could not be answered as written. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, expired or invalid credentials. '403': description: The credentials hold no account allowed to manage this content. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No such resource, or none these credentials can reach — the two are deliberately indistinguishable. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit applied by the API gateway. Back off and retry. '503': description: >- The MCP server registry could not be resolved right now — our infrastructure, not the tenant's servers. Retrying is reasonable. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: AgentToolCatalog: type: object required: - tools - failedServerSlugs properties: tools: type: array description: >- The tools, in no guaranteed order. Empty when the tenant has no MCP server, or none of its servers publishes a tool. items: $ref: '#/components/schemas/AgentTool' failedServerSlugs: type: array description: >- Servers that did not answer; their tools are MISSING from this 200. The catalog is returned partial rather than failed, so a non-empty list here means "incomplete, not empty": a tool you expected may simply live on one of these servers. Retry before concluding a tool does not exist, and never substitute `allTools: true` for a server listed here. items: type: string example: - typebot description: >- The tools available to this tenant's agents, aggregated across every MCP server registered for it. Published tools only. Error: required: - error type: object properties: error: type: string description: What went wrong. example: 'Forbidden: token holds no claim for the requested account' description: Something the caller needs to fix. AgentTool: type: object required: - name - mcpServerSlug - mcpServerId - ref properties: name: type: string description: >- The bare tool name, as the MCP server publishes it. Display value only — it is NOT a whitelist key; use `ref` for that. example: get_order_status description: type: string description: >- What the tool does, as its server describes it. Absent when the server publishes none. example: Looks up the status of an order by its id. inputSchema: type: object additionalProperties: true description: >- JSON Schema of the tool's arguments, exactly as its server publishes it. Free-form: read it, do not assume a shape. Absent when the server publishes none. mcpServerSlug: type: string description: >- Slug of the MCP server this tool comes from. It is the `{slug}` half of `ref`, and the value that appears in `failedServerSlugs` when a server does not answer. example: typebot mcpServerId: type: string description: >- Id of the MCP server this tool comes from — the value that goes in an assistant's `mcp_servers[].id`. Group the refs you want by this field: one `mcp_servers` entry per distinct server id. example: 6683f1c2a4b19e0012ab34cd meta: type: object additionalProperties: true description: >- Free-form extra attributes the publishing server attached to this tool. Absent when it attached none; nothing on this surface requires reading it. ref: type: string description: >- Canonical tool id ({slug}__{tool_name}) and the ONLY value that belongs in an assistant's `mcp_servers[].tools` whitelist. Copy it VERBATIM — do not compose it from `mcpServerSlug` + `name` and never use `name`: the runtime whitelist matches this byte-for-byte, so a hand-built id is silently dropped or hard-rejected. example: typebot__get_order_status description: >- One tool an agent can be given, as published by one of the tenant's MCP servers. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````