Get a tool by ID

import requests
url = "https://example.ada.support/api/v2/tools/507f1f77bcf86cd799439011"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.json())

{
  "id": "507f1f77bcf86cd799439011",
  "type": "api",
  "name": "get_order_status",
  "description": "Look up the status of a customer's order",
  "inputs": [
    {
      "name": "order_id",
      "type": "text",
      "description": "The customer's order number",
      "required": null
    }
  ],
  "outputs": [],
  "enabled": true,
  "direct_use": true,
  "availability": null,
  "api": {
    "url": "https://api.example.com/orders/{var:order_id}",
    "request": {
      "method": "GET",
      "content_type": "json",
      "body": "",
      "headers": [
        {
          "name": "X-Api-Version",
          "value": "2024-01-01"
        }
      ]
    }
  }
}

Returns a single tool in the unified Tool shape, whatever its type. The contract the model sees (name, description, inputs, outputs) and the controls that gate it (enabled, direct_use, availability) sit at the top level; everything specific to how the tool runs is nested under the key matching type.

Authorization headers are stripped from api.request.headers; other header values pass through with variable references translated to the {var:<name>|<default>} form.

Returns a single tool in the unified `Tool` shape, whatever its type. The contract the model sees (`name`, `description`, `inputs`, `outputs`) and the controls that gate it (`enabled`, `direct_use`, `availability`) sit at the top level; everything specific to how the tool runs is nested under the key matching `type`. `Authorization` headers are stripped from `api.request.headers`; other header values pass through with variable references translated to the `{var:<name>|<default>}` form.

Authentication

AuthorizationBearer

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

Path parameters

tool_idstringRequiredformat: "id"

The tool's id

Response

The tool

idstring

The tool's id

typeenum

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

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.

availabilityobject 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

429

Too Many Requests Error

500

Internal Server Error