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

# Criar ferramenta utilizadas durante a chamada

> Crie uma nova ferramenta utilizadas durante a chamada.

Este endpoint permite que você crie uma nova ferramenta utilizadas durante a chamada que pode ser usada por seus assistentes de IA para interagir com APIs externas durante as chamadas.

### Parâmetros do Corpo

<ParamField body="name" type="string" required>
  Nome da ferramenta - deve conter apenas letras minúsculas e sublinhados, e começar com uma letra (ex: `get_weather`, `book_appointment`)
</ParamField>

<ParamField body="description" type="string" required>
  Explicação detalhada de quando e como a IA deve usar esta ferramenta (máx. 255 caracteres)
</ParamField>

<ParamField body="endpoint" type="string" required>
  URL válida do endpoint da API a ser chamado
</ParamField>

<ParamField body="method" type="string" required>
  Método HTTP: `GET`, `POST`, `PUT`, `PATCH`, ou `DELETE`
</ParamField>

<ParamField body="timeout" type="integer" optional>
  Timeout da solicitação em segundos (1-30, padrão: 10)
</ParamField>

<ParamField body="headers" type="array" optional>
  Cabeçalhos HTTP para enviar com a solicitação

  <Expandable title="propriedades de headers">
    <ParamField body="name" type="string" required>
      Nome do cabeçalho
    </ParamField>

    <ParamField body="value" type="string" required>
      Valor do cabeçalho
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="schema" type="array" optional>
  Parâmetros que a IA extrairá da conversa e enviará para o endpoint

  <Expandable title="propriedades de schema">
    <ParamField body="name" type="string" required>
      Nome do parâmetro (2-32 caracteres, deve começar com letra, pode conter letras e sublinhados)
    </ParamField>

    <ParamField body="type" type="string" required>
      Tipo do parâmetro: `string`, `number`, ou `boolean`
    </ParamField>

    <ParamField body="description" type="string" required>
      Descrição para ajudar a IA a entender como extrair este parâmetro (3-255 caracteres)
    </ParamField>
  </Expandable>
</ParamField>

### Campos de resposta

<ResponseField name="message" type="string">
  Mensagem de sucesso
</ResponseField>

<ResponseField name="data" type="object">
  O objeto da ferramenta criada

  <Expandable title="propriedades de data">
    <ResponseField name="id" type="integer">
      O identificador único da ferramenta
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome da ferramenta
    </ResponseField>

    <ResponseField name="description" type="string">
      Descrição da ferramenta
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      URL do endpoint da API
    </ResponseField>

    <ResponseField name="method" type="string">
      Método HTTP
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Timeout da solicitação em segundos
    </ResponseField>

    <ResponseField name="headers" type="array">
      Cabeçalhos HTTP
    </ResponseField>

    <ResponseField name="schema" type="array">
      Esquema de parâmetros
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp ISO 8601
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp ISO 8601
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Ferramenta criada com sucesso",
    "data": {
      "id": 1,
      "name": "check_order_status",
      "description": "Use esta ferramenta para verificar o status do pedido de um cliente.",
      "endpoint": "https://api.sualoja.com/orders/status",
      "method": "GET",
      "timeout": 10,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer sk_..."
        }
      ],
      "schema": [
        {
          "name": "order_id",
          "type": "string",
          "description": "O ID do pedido do cliente"
        },
        {
          "name": "order_number",
          "type": "number",
          "description": "O número numérico do pedido"
        },
        {
          "name": "priority_order",
          "type": "boolean",
          "description": "Se este é um pedido prioritário"
        }
      ],
      "created_at": "2025-10-10T12:00:00.000000Z",
      "updated_at": "2025-10-10T12:00:00.000000Z"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "O campo name deve conter apenas letras minúsculas e sublinhados, e começar com uma letra.",
    "errors": {
      "name": [
        "O nome da ferramenta deve conter apenas letras minúsculas e sublinhados, e começar com uma letra."
      ]
    }
  }
  ```

  ```json 422 Plan Limit Reached theme={null}
  {
    "message": "Você atingiu o limite do seu plano de 5 ferramentas utilizadas durante a chamada. Por favor, atualize seu plano para criar mais ferramentas."
  }
  ```
</ResponseExample>

### Anexando Ferramentas a Assistentes

Após criar uma ferramenta, você precisa anexá-la a um assistente para usá-la durante as chamadas. As ferramentas são gerenciadas através da API de Assistente:

* **[Criar Assistente](/api-reference/assistants/create-assistant)** - Use o parâmetro `tool_ids` para anexar ferramentas ao criar um assistente
* **[Atualizar Assistente](/api-reference/assistants/update-assistant)** - Use o parâmetro `tool_ids` para adicionar, remover ou substituir ferramentas em um assistente existente