> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.altrum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a tool

> Runs one tool call the model asked for and returns the tool's result, ready to send back to the model. Your guardrails check the arguments before the tool runs and the result before it returns.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/mcp/tool/execute
openapi: 3.1.0
info:
  title: Altrum AI Gateway API
  version: 1.0.0
  description: >-
    The public API of the Altrum AI Gateway. It accepts the OpenAI, Anthropic
    and Gemini request formats, so an existing client needs only a new base URL
    and a virtual key.
servers:
  - url: https://api.altrum.ai
security:
  - bearer: []
  - apiKey: []
  - googleApiKey: []
  - altrumKey: []
tags:
  - name: OpenAI
  - name: Anthropic
  - name: Gemini
  - name: MCP
  - name: Health
paths:
  /v1/mcp/tool/execute:
    post:
      tags:
        - MCP
      summary: Run a tool
      description: >-
        Runs one tool call the model asked for and returns the tool's result,
        ready to send back to the model. Your guardrails check the arguments
        before the tool runs and the result before it returns.
      operationId: executeTool
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum:
              - chat
              - responses
            default: chat
          description: The format of the tool call you send and the message you get back.
        - $ref: '#/components/parameters/RequestIdIn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: >-
                With `format=chat`, the tool call from the assistant message
                (`id`, `type`, `function.name`, `function.arguments`). With
                `format=responses`, the Responses function call item (`call_id`,
                `name`, `arguments`).
            example:
              id: call_123
              type: function
              function:
                name: tickets-search
                arguments: '{"query":"refund"}'
      responses:
        '200':
          description: The tool message.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                example:
                  role: tool
                  tool_call_id: call_123
                  content: 3 tickets found.
              example:
                role: tool
                tool_call_id: call_123
                content: 3 tickets found.
        '400':
          description: >-
            The request was refused: a guardrail stopped it, or the body or a
            header is not valid.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIError'
        '401':
          description: No virtual key was sent, or the key does not exist or was revoked.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIError'
        '403':
          description: >-
            The key, AI system, organization, model, provider or tool is not
            allowed.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIError'
        '429':
          description: A rate limit that covers this key was reached.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIError'
components:
  parameters:
    RequestIdIn:
      name: x-request-id
      in: header
      required: false
      description: >-
        Your own reference for the request. Altrum uses it instead of making
        one, and returns it.
      schema:
        type: string
  headers:
    RequestId:
      description: The request's reference. Quote it to support.
      schema:
        type: string
  schemas:
    OpenAIError:
      type: object
      description: An error on the OpenAI routes.
      required:
        - error
      properties:
        type:
          $ref: '#/components/schemas/RefusalCode'
        is_gateway_error:
          type: boolean
        status_code:
          type: integer
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
              description: A refusal code or a stable code.
            message:
              type: string
            param: {}
        request_id:
          type: string
        extra_fields:
          type: object
          additionalProperties: true
      example:
        type: budget_exceeded
        is_gateway_error: true
        status_code: 402
        error:
          type: budget_exceeded
          code: budget_exceeded
          message: 'Budget exceeded: ...'
        request_id: 4f9c...
    RefusalCode:
      type: string
      enum:
        - virtual_key_required
        - access_not_found
        - access_blocked
        - policy_access_denied
        - organization_inactive
        - gateway_disabled
        - ai_system_inactive
        - model_blocked
        - provider_blocked
        - mcp_tool_blocked
        - rate_limited
        - token_limited
        - request_limited
        - organization_concurrency_limit
        - budget_exceeded
        - access_unresolved
        - guardrail_blocked
        - response_blocked
        - guardrail_check_failed
        - payload_too_large
        - prompt_not_found
        - invalid_prompt_version
      description: Why Altrum refused the request.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        Your virtual key, `sk-alt-...`. What every OpenAI and Anthropic SDK
        sends.
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your virtual key, as Anthropic clients send it.
    googleApiKey:
      type: apiKey
      in: header
      name: x-goog-api-key
      description: Your virtual key, as Gemini clients send it.
    altrumKey:
      type: apiKey
      in: header
      name: x-alt-vk
      description: >-
        Your virtual key. Needed when `Authorization` carries your own provider
        key (`x-alt-direct-key`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.