Tools API

The Tools API is a single inventory of the HTTP tools (api) and code tools (code) configured on your AI Agent. Use it to list, fetch, create, update, and delete tools through one Platform API instead of a separate API per type.

Endpoints

List tools (GET /v2/tools/): Returns the Agent’s tools in cursor-paginated pages. See List tools.
Get a tool (GET /v2/tools/{tool_id}): Returns a single tool by its id, including the type-specific body. See Get a tool.
Create a tool (POST /v2/tools/): Creates an api or code tool. See Create a tool.
Update a tool (PATCH /v2/tools/{tool_id}): Partially updates a tool. Write rights depend on type. See Update a tool.
Delete a tool (DELETE /v2/tools/{tool_id}): Soft-deletes an api or code tool. See Delete a tool.

Read and write responses use the shared Tool envelope: id, type, name, description, inputs, outputs, enabled, direct_use, and availability. Required fields that have no value are returned as null rather than omitted.

Tool types

`type`	What it is	Type body on GET
`api`	An HTTP tool (an Action that calls an external API).	`api` — URL, method, headers, and body. `Authorization` headers are never returned.
`code`	A code tool that runs sandboxed Python.	`code` — source code and environment variables.

Code tools require the code tools product entitlement. Without it, they are omitted from the list, and GET /v2/tools/{tool_id} returns 404 for a code tool id. POST of a code tool also fails without the entitlement.

Shared fields

Field	Type	Description
`id`	string	The tool’s unique identifier.
`type`	string	One of `api` or `code`.
`name`	string	The tool’s name, as the model sees it.
`description`	string	What the tool does, as the model sees it.
`inputs`	array	The inputs the tool declares.
`outputs`	array	The values the tool returns.
`enabled`	boolean	Whether the tool is available to the Agent. This is the stored per-tool toggle.
`direct_use`	boolean \| null	Whether the Agent may call this tool on its own, rather than only as a step inside a process.
`availability`	object \| null	The rule that gates when the tool is offered. `null` when the tool is always available. See Availability rules.

List tools

GET /v2/tools/ returns { data, meta: { next_page_url } }.

List items use the same Tool envelope as GET-by-id without the type body. There is no api or code key on a list item. HTTP details and source code belong on a single-tool fetch.

Results are returned in fixed source order: api, then code. Each source is ordered by id.

Query parameters

Parameter	Description
`type`	Restrict the list to one tool type: `api` or `code`. Omitted sources are not queried.
`enabled`	Filter on the tool’s own `enabled` flag. Same meaning for `api` and `code`: the stored per-tool toggle.
`limit`	Maximum tools per page. Integer from `1` to `100`. Default `25`. Values outside that range return `400`.
`cursor`	Opaque pagination token from a previous response’s `meta.next_page_url`. Treat it as opaque, not as an id.

Pagination

The list is cursor-paginated. Read meta.next_page_url from the response and replay it unchanged to fetch the next page. next_page_url is null on the last or empty page. See Pagination.

A cursor is bound to the Agent that minted it and to the type and enabled filters in effect. Changing those filters mid-walk, or presenting another Agent’s cursor, returns 400.

Get a tool

GET /v2/tools/{tool_id} returns one tool in the unified Tool shape. Shared fields sit at the top level; everything specific to how the tool runs is nested under the key matching type (api or code).

Authorization headers are stripped from api.request.headers. Other header values pass through, with variable references in {var:<name>|<default>} form.
An unknown id, an id from another Agent, or a malformed id returns 404 or 400.

Create a tool

POST /v2/tools/ creates an api or code tool and returns the created Tool (201).

type, name, and description are required. type=api requires an api body with url. type=code requires a code body with source_code.
A name that collides with a tool of the other type (api ↔ code) returns 409. Reusing an api name among other api tools is not rejected.
availability is the structured Knowledge rule object, not an internal DSL string. See Availability rules.
Authorization headers on api tools are stored but stripped on every read.
code.environment is optional. source is one of literal, variable, secret, or sensitive_value.
If source is sensitive_value, GET returns an empty value. A GET-then-POST copy does not copy the stored secret. Send the value again.

Update a tool

PATCH /v2/tools/{tool_id} is a merge-patch. Omitted fields are preserved. Nested objects (api, code, api.request) merge key-by-key. Arrays (inputs, outputs, headers, environment) replace when the key is present. Send the complete list, including entries that are not changing.

availability is the one null-delete: omit it to leave the rule untouched, send an object to replace, send null to detach.

Sending a different type, or a type body that does not match the tool (api on a code tool), returns 422. An empty {} body is a no-op 200.

Write rights by type

	`api`	`code`
Control	`enabled`, `direct_use`, `availability`	Same
Contract	`name`, `description`, `inputs`, `outputs`	Same
Implementation	`api.url`, `api.request` (`method`, `content_type`, `body`, `headers`)	`code.source_code`, `code.environment`

Inputs and outputs

name is the identity of each input and output. Other entities hold that name.

Same name with a new description, type, key, source, is_visible_to_llm, or variable.id updates that row.
Adding a name while keeping existing names is allowed. Removing a name (send only what remains) is allowed.
Dropping a stored name and adding a different name in the same PATCH is treated as a rename and returns 422.
Matching by name preserves api output ids, so redactions and other references stay attached when key changes.

Inputs on this API are name, type, and description. The bound variable for an output is variable.id, not variable_id. required on an input is ignored on write. GET always returns it. api and code tools return null.

If headers is omitted from an api PATCH, stored headers, including Authorization, are left in place. Authorization stays stripped on read-back.

If code.environment is present, the array replaces in full. For a sensitive_value row, an empty value leaves the stored secret unchanged. Remove the row to clear it.

A name that collides with another api or code tool returns 409.

Delete a tool

DELETE /v2/tools/{tool_id} soft-deletes an api or code tool and returns 204.

An api tool that other entities still reference returns 409. Code tools have no dependency check.

Authentication

Requests are authenticated with a Bearer API key. See Authentication for details on generating and using API keys.

API keys use the same Platform API permission as other v2 APIs. There are no per-type scopes. One key lists every tool type the Agent is entitled to.