Update a tool

PATCH

https://example.ada.support/api/v2/tools/:tool_id

PATCH

/api/v2/tools/:tool_id

import requests
url = "https://example.ada.support/api/v2/tools/507f1f77bcf86cd799439011"
payload = {
    "enabled": False,
    "api": { "request": { "method": "PUT" } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())

{
  "id": "507f1f77bcf86cd799439011",
  "type": "api",
  "name": "get_order_status",
  "description": "Look up the status of a customer's order",
  "inputs": [],
  "outputs": [],
  "enabled": false,
  "direct_use": true,
  "availability_rules": null,
  "api": {
    "url": "https://api.example.com/orders/{var:order_id}",
    "request": {
      "method": "PUT",
      "content_type": "json",
      "body": "",
      "headers": []
    }
  }
}

Partially update a tool. Omitted fields are preserved.

Nested objects (api, code, api.request) merge key-by-key. Arrays (inputs, outputs, headers, environment) replace in full when the key is present — send the complete list, including entries you are not changing. availability_rules is the one null-delete: omit it to leave the rule untouched, send null to detach, send an object to replace.

For api and code tools, contract, control, and implementation are writable.

Rename an output, or a code input, by sending its id with the new name. A rename without id returns 422. api inputs are name-keyed and cannot be renamed. Editing key, source, or is_visible_to_llm is allowed. Authorization headers stay stripped on read-back.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

tool_idstringRequiredformat: "id"

The tool's id

Request

This endpoint expects an object.

typeenumOptional

If sent, must match the existing tool. Changing type is not supported.

Allowed values:

namestringOptional

descriptionstringOptional

inputslist of objectsOptional

outputslist of objectsOptional

enabledbooleanOptional

direct_usebooleanOptional

availability_rulesobject or nullOptional

A two-level tree of conditions that determines availability based on variable values during a conversation. The root group has a match combinator and a list of conditions or condition groups. A rule may contain at most 1000 conditions in total, counting every condition across the root and all nested condition groups.

apiobjectOptional

Partial api implementation. Omitted keys are preserved.

codeobjectOptional

Partial code implementation. Omitted keys are preserved.

Response

The updated tool

idstring

The tool's id

typeenum

Which kind of tool this is, and which implementation key is present

Allowed values:

namestring

The tool's name, as the model sees it

descriptionstring

What the tool does, as the model sees it

inputslist of objects

The inputs the tool declares

outputslist of objects

The values the tool returns.

enabledboolean

Whether the tool is available to the Agent at all

direct_useboolean or null

Whether the Agent may call this tool on its own, rather than only as a step inside a process.

availability_rulesobject or null

The rule that gates when the tool is offered. null when the tool is always available.

apiobjectOptional

How an api tool calls its HTTP endpoint

codeobjectOptional

The sandboxed Python a code tool runs

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error