> ## Documentation Index
> Fetch the complete documentation index at: https://developers.insuranceboosters.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Actualizar herramienta

> Actualiza campos de una herramienta de agente.

Actualiza una herramienta. Envía siempre su `toolType` actual y agrega solo los
campos que quieras cambiar. No uses esta operación para convertirla a otro tipo.

## Endpoint

```text theme={null}
PUT /tools/{toolId}
```

Si actualizas una herramienta HTTP y envías `details`, incluye el objeto
completo con `endpoint`, `method` y `authentication`. Para `run_code`,
`details` debe incluir `code`. En todos los tipos, `details` reemplaza el objeto
anterior; incluye los valores que quieras conservar.

## Ejemplo de solicitud

```bash theme={null}
curl -X PUT "https://api.insuranceboosters.com/api/v1/tools/<tool-id>" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "toolType": "http",
    "instructions": "Consulta los datos vigentes de un cliente por su identificador.",
    "details": {
      "endpoint": "https://api.ejemplo.com/clientes/{{clienteId}}",
      "method": "GET",
      "authentication": {
        "type": "bearer",
        "token": "<token-secreto>"
      }
    }
  }'
```

> [!WARNING]
>
> `details.authentication.token` es un secreto. Usa un placeholder en ejemplos y protégelo con el mismo cuidado que una credencial.

Consulta [Tipos de herramienta](https://developers.insuranceboosters.com/agentes/herramientas/tipos-de-herramienta.md)
para conocer los campos específicos de cada `toolType`.

## Respuesta exitosa (`200`)

Devuelve la herramienta actualizada con su configuración completa, incluidos
`tenantId`, `deleted`, `createdAt` y `lastUpdatedAt`.

> [!WARNING]
>
> La respuesta no redacta tokens, headers ni código. Trátala como un secreto.

## Errores frecuentes

| HTTP | Qué significa | Qué hacer |
| - | - | - |
| `400` | El body no cumple el esquema. | Incluye el `toolType` actual y revisa los campos enviados. |
| `401` | API key inválida o faltante. | Verifica `x-ib-api-key`. |
| `403` | La operación no está permitida. | Revisa la solicitud o contacta soporte. |
| `404` | No se encontró la herramienta. | Confirma `toolId`. |
| `503` | El servicio no está disponible temporalmente. | Reintenta; si continúa, contacta soporte. |
| `500` | No fue posible actualizar la herramienta. | Reintenta; si continúa, contacta soporte. |


## OpenAPI

````yaml openapi/herramientas-agentes-v1.yaml PUT /tools/{toolId}
openapi: 3.1.0
info:
  title: Insurance Boosters API — Herramientas de agentes IA
  version: 1.0.0
  description: >-
    API pública para administrar y probar las herramientas que pueden usar tus
    agentes de IA.
  license:
    name: Propietaria
    url: https://insuranceboosters.com
servers:
  - url: https://api.insuranceboosters.com/api/v1
    description: Producción
security:
  - IbApiKey: []
tags:
  - name: Herramientas de agentes
    description: Administración de herramientas para agentes de IA.
paths:
  /tools/{toolId}:
    put:
      tags:
        - Herramientas de agentes
      summary: Actualizar herramienta
      description: >
        Actualiza los campos enviados de una herramienta. `toolType` siempre es
        obligatorio y debe corresponder al tipo actual de la herramienta.
      operationId: updateAgentTool
      parameters:
        - $ref: '#/components/parameters/ToolId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateToolRequest'
            example:
              toolType: http
              instructions: Consulta los datos vigentes de un cliente por su identificador.
      responses:
        '200':
          description: Herramienta actualizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ToolNotFound'
        '500':
          $ref: '#/components/responses/UnexpectedError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    ToolId:
      name: toolId
      in: path
      required: true
      description: Identificador de la herramienta.
      schema:
        type: string
      example: tool_01
  schemas:
    UpdateToolRequest:
      oneOf:
        - $ref: '#/components/schemas/UpdateHttpTool'
        - $ref: '#/components/schemas/UpdateHumanHandoffTool'
        - $ref: '#/components/schemas/UpdateConversationEndedTool'
        - $ref: '#/components/schemas/UpdatePhoneConnectTool'
        - $ref: '#/components/schemas/UpdateDepartmentAvailabilityTool'
        - $ref: '#/components/schemas/UpdateRunCodeTool'
      discriminator:
        propertyName: toolType
        mapping:
          http: '#/components/schemas/UpdateHttpTool'
          human_handoff: '#/components/schemas/UpdateHumanHandoffTool'
          conversation_ended: '#/components/schemas/UpdateConversationEndedTool'
          phone_connect: '#/components/schemas/UpdatePhoneConnectTool'
          department_availability: '#/components/schemas/UpdateDepartmentAvailabilityTool'
          run_code: '#/components/schemas/UpdateRunCodeTool'
    ToolResponse:
      description: >
        Configuración completa de una herramienta. Las respuestas HTTP y de
        código no se redactan: pueden contener tokens, headers y código.
      oneOf:
        - $ref: '#/components/schemas/HttpToolResponse'
        - $ref: '#/components/schemas/HumanHandoffToolResponse'
        - $ref: '#/components/schemas/ConversationEndedToolResponse'
        - $ref: '#/components/schemas/PhoneConnectToolResponse'
        - $ref: '#/components/schemas/DepartmentAvailabilityToolResponse'
        - $ref: '#/components/schemas/RunCodeToolResponse'
      discriminator:
        propertyName: toolType
        mapping:
          http: '#/components/schemas/HttpToolResponse'
          human_handoff: '#/components/schemas/HumanHandoffToolResponse'
          conversation_ended: '#/components/schemas/ConversationEndedToolResponse'
          phone_connect: '#/components/schemas/PhoneConnectToolResponse'
          department_availability: '#/components/schemas/DepartmentAvailabilityToolResponse'
          run_code: '#/components/schemas/RunCodeToolResponse'
    UpdateHttpTool:
      allOf:
        - $ref: '#/components/schemas/UpdateBaseFields'
        - $ref: '#/components/schemas/UpdateHttpToolRequest'
    UpdateHumanHandoffTool:
      allOf:
        - $ref: '#/components/schemas/UpdateBaseFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: human_handoff
            loadingText:
              type: string
            details:
              $ref: '#/components/schemas/HumanHandoffDetails'
    UpdateConversationEndedTool:
      allOf:
        - $ref: '#/components/schemas/UpdateBaseFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: conversation_ended
            details:
              type: object
    UpdatePhoneConnectTool:
      allOf:
        - $ref: '#/components/schemas/UpdateBaseFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: phone_connect
            loadingText:
              type: string
            showLoadingText:
              type: boolean
            details:
              $ref: '#/components/schemas/PhoneConnectDetails'
    UpdateDepartmentAvailabilityTool:
      allOf:
        - $ref: '#/components/schemas/UpdateBaseFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: department_availability
            loadingText:
              type: string
            showLoadingText:
              type: boolean
            details:
              $ref: '#/components/schemas/DepartmentAvailabilityDetails'
            inputs:
              type: array
              items:
                $ref: '#/components/schemas/DepartmentAvailabilityInput'
    UpdateRunCodeTool:
      allOf:
        - $ref: '#/components/schemas/UpdateBaseFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: run_code
            details:
              $ref: '#/components/schemas/RunCodeDetails'
    HttpToolResponse:
      allOf:
        - $ref: '#/components/schemas/HttpToolFields'
        - type: object
          required:
            - id
            - tenantId
            - createdAt
            - lastUpdatedAt
          properties:
            id:
              type: string
              description: Identificador de la herramienta.
            tenantId:
              type: string
              description: Identificador asociado a la herramienta.
            deleted:
              type: boolean
              description: >-
                Estado de eliminación lógica. Las operaciones de lectura omiten
                herramientas eliminadas.
            createdAt:
              type: number
              description: Fecha de creación en milisegundos desde epoch.
            lastUpdatedAt:
              type: number
              description: Fecha de la última actualización en milisegundos desde epoch.
          additionalProperties: true
    HumanHandoffToolResponse:
      allOf:
        - $ref: '#/components/schemas/HumanHandoffTool'
        - $ref: '#/components/schemas/ResponseMetadata'
    ConversationEndedToolResponse:
      allOf:
        - $ref: '#/components/schemas/ConversationEndedTool'
        - $ref: '#/components/schemas/ResponseMetadata'
    PhoneConnectToolResponse:
      allOf:
        - $ref: '#/components/schemas/PhoneConnectTool'
        - $ref: '#/components/schemas/ResponseMetadata'
    DepartmentAvailabilityToolResponse:
      allOf:
        - $ref: '#/components/schemas/DepartmentAvailabilityTool'
        - $ref: '#/components/schemas/ResponseMetadata'
    RunCodeToolResponse:
      allOf:
        - $ref: '#/components/schemas/RunCodeTool'
        - $ref: '#/components/schemas/ResponseMetadata'
    Error:
      type: object
      properties:
        success:
          type: boolean
          description: Vale `false` cuando la operación no se completa.
        error:
          description: Detalle del error.
        message:
          type: string
          description: Mensaje del error.
        code:
          type: string
          description: Código del error, cuando está disponible.
    UpdateBaseFields:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        apiName:
          type: string
          minLength: 1
          description: No uses el nombre reservado `endTurn`.
        instructions:
          type: string
          minLength: 1
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/InputParameter'
        loadingText:
          type: string
        showLoadingText:
          type: boolean
    UpdateHttpToolRequest:
      type: object
      required:
        - toolType
      properties:
        name:
          type: string
          minLength: 1
        apiName:
          type: string
          minLength: 1
        instructions:
          type: string
          minLength: 1
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/InputParameter'
        toolType:
          type: string
          const: http
        details:
          $ref: '#/components/schemas/HttpDetails'
          description: Si actualizas la configuración HTTP, envía el objeto completo.
        storeOutputAsVariable:
          type: boolean
        outputVariableName:
          type: string
        outputVariablePath:
          type: string
    HumanHandoffDetails:
      type: object
      properties:
        allowedDepartments:
          type: array
          description: >-
            IDs de los departamentos permitidos. Si lo omites o envías vacío, se
            permiten todos.
          items:
            type: string
        userNotificationMessage:
          type: string
          default: I'm connecting you with a human agent who can better assist you.
          description: Mensaje que recibe el usuario cuando se completa la transferencia.
    PhoneConnectDetails:
      type: object
      properties:
        ringTimeoutSeconds:
          type: number
          minimum: 5
          maximum: 120
          description: Segundos que puede sonar la llamada.
        retryAttempts:
          type: number
          minimum: 0
          maximum: 10
          description: Cantidad de reintentos configurada para la conexión.
        noAnswerMessage:
          type: string
          maxLength: 500
          description: Mensaje que se usa cuando nadie contesta.
    DepartmentAvailabilityDetails:
      type: object
      properties:
        allowedDepartments:
          type: array
          minItems: 1
          description: >-
            IDs de los departamentos que se pueden consultar. Si lo omites, se
            consultan todos.
          items:
            type: string
        includeFormattedSchedule:
          type: boolean
          description: Indica si el resultado incluye un resumen legible de horarios.
    DepartmentAvailabilityInput:
      type: object
      required:
        - name
        - type
        - description
        - required
      properties:
        name:
          type: string
          const: departmentId
        type:
          type: string
          const: string
        description:
          type: string
        required:
          type: boolean
          const: false
        default:
          type: string
          default: ''
    RunCodeDetails:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 100000
          description: >
            Código JavaScript. Lee los datos desde `input`, asigna un objeto
            JSON a `output` y no incluyas secretos directamente en el código.
        network:
          $ref: '#/components/schemas/RunCodeNetwork'
    HttpToolFields:
      type: object
      required:
        - name
        - apiName
        - instructions
        - toolType
        - details
      properties:
        name:
          type: string
          minLength: 1
          description: Nombre visible de la herramienta.
        apiName:
          type: string
          minLength: 1
          description: Nombre que el agente usa para llamar la herramienta.
        instructions:
          type: string
          minLength: 1
          description: Explica al agente cuándo y para qué debe usarla.
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/InputParameter'
        loadingText:
          type: string
          description: Texto que puedes mostrar mientras se ejecuta la herramienta.
        showLoadingText:
          type: boolean
          description: Indica si se muestra `loadingText` durante la ejecución.
        toolType:
          type: string
          const: http
        details:
          $ref: '#/components/schemas/HttpDetails'
        storeOutputAsVariable:
          type: boolean
          description: Indica si la respuesta se guarda como variable de sesión.
        outputVariableName:
          type: string
          description: Nombre de la variable donde se guarda la respuesta.
        outputVariablePath:
          type: string
          description: >-
            Ruta con notación de puntos para extraer una parte de la respuesta
            JSON.
    HumanHandoffTool:
      allOf:
        - $ref: '#/components/schemas/BaseToolFields'
        - type: object
          required:
            - toolType
            - details
          properties:
            toolType:
              type: string
              const: human_handoff
            loadingText:
              type: string
              description: Texto que se puede mostrar mientras se procesa la transferencia.
            details:
              $ref: '#/components/schemas/HumanHandoffDetails'
    ResponseMetadata:
      type: object
      required:
        - id
        - tenantId
        - createdAt
        - lastUpdatedAt
      properties:
        id:
          type: string
          description: Identificador de la herramienta.
        tenantId:
          type: string
          description: Identificador asociado a la herramienta.
        deleted:
          type: boolean
          description: Estado de eliminación lógica.
        createdAt:
          type: number
          description: Fecha de creación en milisegundos desde epoch.
        lastUpdatedAt:
          type: number
          description: Fecha de la última actualización en milisegundos desde epoch.
    ConversationEndedTool:
      allOf:
        - $ref: '#/components/schemas/BaseToolFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: conversation_ended
            details:
              type: object
              description: Configuración vacía; usa `{}`.
    PhoneConnectTool:
      allOf:
        - $ref: '#/components/schemas/BaseToolFields'
        - type: object
          required:
            - toolType
            - details
          properties:
            toolType:
              type: string
              const: phone_connect
            loadingText:
              type: string
            showLoadingText:
              type: boolean
            details:
              $ref: '#/components/schemas/PhoneConnectDetails'
    DepartmentAvailabilityTool:
      allOf:
        - $ref: '#/components/schemas/BaseToolFields'
        - type: object
          required:
            - toolType
          properties:
            toolType:
              type: string
              const: department_availability
            loadingText:
              type: string
            showLoadingText:
              type: boolean
            details:
              $ref: '#/components/schemas/DepartmentAvailabilityDetails'
            inputs:
              type: array
              items:
                $ref: '#/components/schemas/DepartmentAvailabilityInput'
    RunCodeTool:
      allOf:
        - $ref: '#/components/schemas/BaseToolFields'
        - type: object
          required:
            - toolType
            - details
          properties:
            toolType:
              type: string
              const: run_code
            details:
              $ref: '#/components/schemas/RunCodeDetails'
    InputParameter:
      type: object
      required:
        - name
        - type
        - description
        - required
      properties:
        name:
          type: string
          description: Nombre usado en los placeholders de la configuración HTTP.
          example: clienteId
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - enum
            - object
          description: Tipo de valor que acepta el parámetro.
        description:
          type: string
          description: Explica al agente qué dato debe enviar.
        required:
          type: boolean
          description: Indica si el agente siempre debe proporcionar el parámetro.
        collectFromUser:
          type: boolean
          default: false
          description: >-
            Si es `true`, el agente puede pedir el valor al usuario cuando haga
            falta.
        examples:
          type: array
          description: Valores de ejemplo que ayudan al agente a reconocer el formato.
          items:
            type: string
        options:
          type: array
          minItems: 1
          description: >-
            Valores permitidos. Es obligatorio para `enum` y no se envía para
            otros tipos.
          items:
            type: string
        default:
          description: >-
            Valor predeterminado para un parámetro opcional. Debe coincidir con
            `type`.
    HttpDetails:
      type: object
      required:
        - endpoint
        - method
        - authentication
      properties:
        endpoint:
          type: string
          description: >-
            URL que recibirá la solicitud. Admite placeholders como
            `{{clienteId}}`.
          example: https://api.ejemplo.com/clientes/{{clienteId}}
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - PATCH
        headers:
          type: object
          description: >-
            Headers adicionales. Los valores deben ser strings y admiten
            placeholders.
          additionalProperties:
            type: string
        queryParams:
          type: object
          description: >-
            Parámetros de consulta. Los valores deben ser strings y admiten
            placeholders.
          additionalProperties:
            type: string
        body:
          type: object
          description: Body JSON. Sus valores admiten placeholders.
          additionalProperties: true
        authentication:
          $ref: '#/components/schemas/HttpAuthentication'
    RunCodeNetwork:
      type: object
      required:
        - enabled
      properties:
        enabled:
          type: boolean
          description: Habilita `fetch`, `axios`, `Headers`, `Request` y `Response`.
    BaseToolFields:
      type: object
      required:
        - name
        - apiName
        - instructions
      properties:
        name:
          type: string
          minLength: 1
          description: Nombre visible de la herramienta.
        apiName:
          type: string
          minLength: 1
          description: >
            Nombre que usa el agente para llamar la herramienta. No uses
            `endTurn`, porque está reservado por el agente.
        instructions:
          type: string
          minLength: 1
          description: Explica al agente cuándo y para qué debe usar la herramienta.
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/InputParameter'
    HttpAuthentication:
      oneOf:
        - $ref: '#/components/schemas/NoAuthentication'
        - $ref: '#/components/schemas/BearerAuthentication'
      discriminator:
        propertyName: type
    NoAuthentication:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          const: no_auth
    BearerAuthentication:
      type: object
      required:
        - type
        - token
      properties:
        type:
          type: string
          const: bearer
        token:
          type: string
          minLength: 1
          format: password
          description: 'Token secreto que se enviará como `Authorization: Bearer <token>`.'
          example: <token-secreto>
  responses:
    InvalidBody:
      description: El body no cumple el esquema.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            issues:
              summary: Crear o actualizar
              value:
                error:
                  - code: too_small
                    path:
                      - name
                    message: Name is required
            flattened:
              summary: Probar código
              value:
                error:
                  formErrors: []
                  fieldErrors:
                    details:
                      - Required
    Unauthorized:
      description: API key inválida o faltante.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidApiKey:
              value:
                message: Invalid API key.
            missingAuth:
              value:
                message: Invalid authorization format.
    Forbidden:
      description: La operación no está permitida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ToolNotFound:
      description: No se encontró la herramienta.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnexpectedError:
      description: Error inesperado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: El servicio no está disponible temporalmente.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    IbApiKey:
      type: apiKey
      in: header
      name: x-ib-api-key

````

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