Tools

Manage the full lifecycle of tools programmatically: create them, configure their type-specific behavior and arguments, publish and roll back versions, import entire MCP servers as tool sets, and control sharing and ownership.

All paths on this page are relative to https://api.autessa.com/autessa_poweruser/tools. Every request is a POST with a JSON body, and every ID is an opaque string. See the Poweruser API overview for authentication and conventions.

The tool object

Tools are self-contained actions that agents can call. What a tool actually does is determined by its toolConfig — the toolType selects one of the platform's tool implementations, and the config map carries that type's fields.

Name
toolId
Type
string
Description
Unique tool identifier.
Name
companyId
Type
string
Description
The owning company.
Name
name
Type
string
Description
Display name. This is also the function name the model sees, so keep it descriptive.
Name
description
Type
string
Description
What the tool does. The model uses this when deciding whether to call the tool.
Name
toolConfig
Type
object
Description
The tool's behavior: toolType (string — which implementation runs, e.g. AUTESSA_SCRIPT, API_CALL, LLM_CALL, SEND_EMAIL, AUTESSADB_QUERY_TABLE, MCP, and the rest of the tool-type catalog) and config (object — that type's configuration fields). The per-type fields are documented in the tool-type reference. Config values may contain {{argumentName}} placeholders that are filled from the tool's arguments at execution time.
Name
parsedToolConfig
Type
object
Description
Server-populated typed view of toolConfig for the tool's type. Read-only — send changes through toolConfig.
Name
arguments
Type
object
Description
Map of argument name to definition (description, isRequired, argumentSchema — a JSON Schema object). These are the parameters the model fills when calling the tool.
Name
privateArguments
Type
object
Description
Map of argument name to private-argument definition. Same fields as arguments plus messageToUser (string — the prompt shown when the value is collected from the end user), regexValidation (string), and allowedValues (array<string>). Private argument values are never seen or filled by the model.
Name
lastPublishedTime
Type
string
Description
ISO-8601 timestamp of the last publish, or absent if never published.
Name
tags
Type
array<string>
Description
Free-form organizational tags. Tools created from MCP servers are tagged with mcp and the server's hostname.

Tool object
{
  "toolId": "kZ3mQ9pW2x",
  "companyId": "cP2mK7dX4v",
  "name": "SendOrderUpdate",
  "description": "Emails the customer an update about their order.",
  "toolConfig": {
    "toolType": "SEND_EMAIL",
    "config": {
      "recipientEmail": "{{recipientEmail}}",
      "subject": "Update on your order",
      "messageBody": "{{updateText}}"
    }
  },
  "arguments": {
    "recipientEmail": {
      "description": "Email address of the customer",
      "isRequired": true,
      "argumentSchema": { "type": "string" }
    },
    "updateText": {
      "description": "The update to send",
      "isRequired": true,
      "argumentSchema": { "type": "string" }
    }
  },
  "privateArguments": {},
  "lastPublishedTime": "2026-06-28T17:42:10",
  "tags": ["support"]
}

Versioning and access levels

Tools follow the platform-wide draft/published model (see the Versions guide):

Draft — /update always edits the draft working copy.
Published — /publish snapshots the draft as a new published version; the previously published version becomes archived.
Rollback — /rollback republishes an archived version without touching the draft.

Endpoints enforce the caller's access level on the tool (the poweruser key acts as its linked user):

Operation	Required access
`get`, `all`, `versions`, `get-sharing-details`	Any access (READ or higher)
`update`	WRITE, PUBLISH, or ADMIN
`publish`, `rollback`	PUBLISH or ADMIN
`delete`, `share`	ADMIN
`transfer-ownership`	Owner only

Create a tool

POST/tools/create

Creates a new tool as a private draft. toolName and toolDescription are both required — creation fails with an error message if either is blank. The new tool starts with a placeholder AUTESSA_SCRIPT config; set the real toolType, toolConfig, and arguments with /update, then /publish to make it usable by published agents.

See the tool-type reference for the configuration fields each toolType accepts.

Request parameters

Name
toolName
Type
string
Description
Display name. Must be non-blank.
Name
toolDescription
Type
string
Description
Description of what the tool does. Must be non-blank — the model relies on it to pick the right tool.

Response

Name
tool
Type
Tool
Description
The newly created tool object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/tools/create \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "SendOrderUpdate",
    "toolDescription": "Emails the customer an update about their order."
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/tools/create',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      toolName: 'SendOrderUpdate',
      toolDescription: 'Emails the customer an update about their order.'
    })
  }
);

const { tool } = await response.json();
console.log(tool.toolId);

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/tools/create',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={
        'toolName': 'SendOrderUpdate',
        'toolDescription': 'Emails the customer an update about their order.'
    }
)

tool = response.json()['tool']

Response (truncated)
{
  "tool": {
    "toolId": "kZ3mQ9pW2x",
    "companyId": "cP2mK7dX4v",
    "name": "SendOrderUpdate",
    "description": "Emails the customer an update about their order.",
    "toolConfig": {
      "toolType": "AUTESSA_SCRIPT",
      "config": { "script": "..." }
    },
    "arguments": {},
    "privateArguments": {}
  },
  "errors": []
}

Get a tool

POST/tools/get

Retrieves a tool's full configuration. Without a version parameter you get the current draft working copy; pass version to read a specific published or archived snapshot.

Request parameters

Name
toolId
Type
string
Description
The tool to fetch.
Name
version
Type
object
Description
Optional version selector: versionState (PUBLISHED, DRAFT, or ARCHIVED; defaults to PUBLISHED when the object is present) and an optional versionNumber.

Response

Name
tool
Type
Tool
Description
The tool object.
Name
permission
Type
string
Description
The calling user's access level on this tool: READ, WRITE, PUBLISH, or ADMIN.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/tools/get \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "kZ3mQ9pW2x",
    "version": { "versionState": "PUBLISHED" }
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/tools/get',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ toolId: 'kZ3mQ9pW2x' })
  }
);

const { tool, permission } = await response.json();

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/tools/get',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={'toolId': 'kZ3mQ9pW2x'}
)

data = response.json()

Response (truncated)
{
  "tool": {
    "toolId": "kZ3mQ9pW2x",
    "name": "SendOrderUpdate",
    "toolConfig": { "toolType": "SEND_EMAIL", "config": { "subject": "Update on your order" } }
  },
  "permission": "ADMIN",
  "errors": []
}

List all tools

POST/tools/all

Lists every tool visible to the linked user, grouped by how they have access. Entries are lightweight summaries — use /get for the full configuration.

Request parameters

None — send an empty object {}.

Response

Name
ownedTools
Type
array<Tool>
Description
Tools the linked user owns.
Name
companySharedTools
Type
array<Tool>
Description
Tools shared with the whole company.
Name
sharedWithMeTools
Type
array<Tool>
Description
Tools shared specifically with the linked user.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/tools/all \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response
{
  "ownedTools": [
    {
      "toolId": "kZ3mQ9pW2x",
      "name": "SendOrderUpdate",
      "description": "Emails the customer an update about their order.",
      "tags": ["support"],
      "lastPublishedTime": "2026-06-28T17:42:10"
    }
  ],
  "companySharedTools": [],
  "sharedWithMeTools": [],
  "errors": []
}

Update a tool

POST/tools/update

Replaces the tool's draft configuration with updatedTool. This is a whole-object update: fetch the draft with /get, modify it, and send the full object back. Published versions are unaffected until you /publish.

This is where you set the tool's real behavior — toolConfig.toolType selects the implementation and toolConfig.config carries its fields. The required and optional config fields for every type are listed in the tool-type reference. Define the model-facing parameters in arguments and reference them from config values as {{argumentName}}.

Requires WRITE, PUBLISH, or ADMIN access.

Request parameters

Name
toolId
Type
string
Description
The tool to update.
Name
updatedTool
Type
Tool
Description
The complete tool object to store as the new draft, using the tool object shape.

Response

Name
updatedTool
Type
Tool
Description
The stored draft.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/tools/update \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "kZ3mQ9pW2x",
    "updatedTool": {
      "toolId": "kZ3mQ9pW2x",
      "name": "SendOrderUpdate",
      "description": "Emails the customer an update about their order.",
      "toolConfig": {
        "toolType": "SEND_EMAIL",
        "config": {
          "recipientEmail": "{{recipientEmail}}",
          "subject": "Update on your order",
          "messageBody": "{{updateText}}"
        }
      },
      "arguments": {
        "recipientEmail": {
          "description": "Email address of the customer",
          "isRequired": true,
          "argumentSchema": { "type": "string" }
        },
        "updateText": {
          "description": "The update to send",
          "isRequired": true,
          "argumentSchema": { "type": "string" }
        }
      },
      "privateArguments": {}
    }
  }'

// Read-modify-write the draft
const base = 'https://api.autessa.com/autessa_poweruser/tools';
const headers = {
  'Authorization': process.env.POWERUSER_KEY,
  'Content-Type': 'application/json'
};

const getResp = await fetch(`${base}/get`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ toolId: 'kZ3mQ9pW2x' })
});
const { tool } = await getResp.json();

tool.toolConfig = {
  toolType: 'SEND_EMAIL',
  config: {
    recipientEmail: '{{recipientEmail}}',
    subject: 'Update on your order',
    messageBody: '{{updateText}}'
  }
};

await fetch(`${base}/update`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ toolId: tool.toolId, updatedTool: tool })
});

import os
import requests

headers = {'Authorization': os.environ['POWERUSER_KEY']}
base = 'https://api.autessa.com/autessa_poweruser/tools'

tool = requests.post(f'{base}/get', headers=headers,
                     json={'toolId': 'kZ3mQ9pW2x'}).json()['tool']

tool['toolConfig'] = {
    'toolType': 'SEND_EMAIL',
    'config': {
        'recipientEmail': '{{recipientEmail}}',
        'subject': 'Update on your order',
        'messageBody': '{{updateText}}'
    }
}

requests.post(f'{base}/update', headers=headers,
              json={'toolId': tool['toolId'], 'updatedTool': tool})

Response (truncated)
{
  "updatedTool": {
    "toolId": "kZ3mQ9pW2x",
    "name": "SendOrderUpdate",
    "toolConfig": { "toolType": "SEND_EMAIL", "config": { "subject": "Update on your order" } }
  },
  "errors": []
}

Publish a tool

POST/tools/publish

Snapshots the current draft as a new published version. Agents that use the tool's published version pick up the change; the previously published version becomes archived and remains available for /rollback.

Requires PUBLISH or ADMIN access.

Request parameters

Name
toolId
Type
string
Description
The tool to publish.

Response

Name
publishedToolVersion
Type
integer
Description
The new published version number.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/tools/publish \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolId": "kZ3mQ9pW2x" }'

Response
{
  "publishedToolVersion": 3,
  "errors": []
}

Roll back a tool

POST/tools/rollback

Republishes an archived version, making it the live published version again. The draft working copy is not changed. Use /versions to find rollback candidates. versionToRollback is required.

Requires PUBLISH or ADMIN access.

Request parameters

Name
toolId
Type
string
Description
The tool to roll back.
Name
versionToRollback
Type
integer
Description
The archived version number to republish.

Response

Name
newPublishedVersion
Type
integer
Description
The version number now published.
Name
errors
Type
array<string>
Description
Error messages, if any occurred (for example "Failed to rollback tool to specified version").

cURL
curl https://api.autessa.com/autessa_poweruser/tools/rollback \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolId": "kZ3mQ9pW2x", "versionToRollback": 2 }'

Response
{
  "newPublishedVersion": 4,
  "errors": []
}

List versions

POST/tools/versions

Returns the tool's published version and all archived version numbers.

Request parameters

Name
toolId
Type
string
Description
The tool to inspect.

Response

Name
currentPublishedVersion
Type
integer
Description
The live published version, or absent if the tool was never published.
Name
archivedVersions
Type
array<integer>
Description
Previously published version numbers available for rollback.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/tools/versions \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolId": "kZ3mQ9pW2x" }'

Response
{
  "currentPublishedVersion": 3,
  "archivedVersions": [1, 2],
  "errors": []
}

Create tools from an MCP server

POST/tools/create-from-mcp

Connects to a registered MCP server, lists its tools, and creates one Autessa tool per MCP tool. Each created tool:

has toolType: MCP bound to the server and the MCP tool's name,
gets its arguments parsed from the MCP tool's JSON Schema input schema,
is tagged with mcp and the server's hostname.

Creation is best-effort per tool: if one MCP tool fails to convert, the rest are still created. An error is returned only when the server can't be reached, exposes no tools, or every conversion fails. Register servers first through the MCP API.

Request parameters

Name
mcpServerId
Type
string
Description
The registered MCP server to import tools from.

Response

Name
createdTools
Type
array<Tool>
Description
The tools that were created, one per MCP tool.
Name
errors
Type
array<string>
Description
Error messages, if any occurred (for example "MCP server not found or access denied" or "No tools found on MCP server").

cURL
curl https://api.autessa.com/autessa_poweruser/tools/create-from-mcp \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcpServerId": "mQ4xT8rY2b" }'

Response (truncated)
{
  "createdTools": [
    {
      "toolId": "pR7vN2sK9j",
      "name": "search_issues",
      "description": "Search issues in the tracker.",
      "toolConfig": {
        "toolType": "MCP",
        "config": {
          "mcpServerId": "mQ4xT8rY2b",
          "mcpToolName": "search_issues"
        }
      },
      "tags": ["mcp", "mcp_example_com"]
    }
  ],
  "errors": []
}

POST/tools/share

Sets the tool's sharing level and per-user grants in one call.

Requires ADMIN access on the tool.

Request parameters

Name
toolId
Type
string
Description
The tool to share.
Name
level
Type
string
Description
Sharing level: PRIVATE, SPECIFIC_MEMBER, or COMPANY.
Name
accessLevel
Type
string
Description
When level is COMPANY, the access level every company member gets: READ, WRITE, PUBLISH, or ADMIN.
Name
usersToAdd
Type
array<UserShare>
Description
Users to grant access. Each entry: userEmail or userId (string), plus accessLevel.
Name
usersToRemove
Type
array<UserShare>
Description
Users whose access to revoke, same entry shape.

Response

Name
level
Type
string
Description
The resulting sharing level.
Name
accessLevel
Type
string
Description
The resulting company-wide access level, when shared with the company.
Name
usersWithAccess
Type
array<UserShare>
Description
The resulting per-user grants (populated when the tool is shared with specific members).
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/tools/share \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "kZ3mQ9pW2x",
    "level": "SPECIFIC_MEMBER",
    "usersToAdd": [
      { "userEmail": "sam@acme.com", "accessLevel": "WRITE" }
    ],
    "usersToRemove": []
  }'

Response
{
  "level": "SPECIFIC_MEMBER",
  "usersWithAccess": [
    {
      "userEmail": "sam@acme.com",
      "userId": "uB7nT2wQ9k",
      "accessLevel": "WRITE"
    }
  ],
  "errors": []
}

POST/tools/get-sharing-details

Returns the tool's current sharing configuration and the calling user's own access level.

Request parameters

Name
toolId
Type
string
Description
The tool to inspect.

Response

Name
sharingLevel
Type
string
Description
PRIVATE, SPECIFIC_MEMBER, or COMPANY.
Name
companyPermissionLevel
Type
string
Description
Access level granted company-wide, when sharingLevel is COMPANY.
Name
sharedWith
Type
array<UserShare>
Description
Per-user grants: userEmail, userId, accessLevel.
Name
userAccessLevel
Type
string
Description
The calling user's effective access level.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/tools/get-sharing-details \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolId": "kZ3mQ9pW2x" }'

Response
{
  "sharingLevel": "SPECIFIC_MEMBER",
  "companyPermissionLevel": null,
  "sharedWith": [
    {
      "userEmail": "sam@acme.com",
      "userId": "uB7nT2wQ9k",
      "accessLevel": "WRITE"
    }
  ],
  "userAccessLevel": "ADMIN",
  "errors": []
}

Delete a tool

POST/tools/delete

Permanently deletes a tool, including its draft and version history. The delete is refused with a 422 status while any agent still uses the tool — the errors array names each blocking agent, for example "Support Triage Agent is currently using tool. Remove all usages before deleting". Detach the tool from those agents first.

Requires ADMIN access on the tool.

Request parameters

Name
toolId
Type
string
Description
The tool to delete.

Response

Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/tools/delete \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolId": "kZ3mQ9pW2x" }'

Response
{
  "errors": []
}

Response (tool still in use, HTTP 422)
{
  "errors": [
    "Support Triage Agent is currently using tool. Remove all usages before deleting"
  ]
}

Transfer ownership

POST/tools/transfer-ownership

Transfers the tool to another member of the company. Only the current owner may call this, and the new owner must already have some access to the tool (share it with them first).

Request parameters

Name
toolId
Type
string
Description
The tool to transfer.
Name
newOwnerId
Type
string
Description
User ID of the new owner. Must be a member of the company with existing access to the tool.

Response

Name
errors
Type
array<string>
Description
Error messages, if any occurred (for example "New owner does not have access to tool yet.").

cURL
curl https://api.autessa.com/autessa_poweruser/tools/transfer-ownership \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "kZ3mQ9pW2x",
    "newOwnerId": "uB7nT2wQ9k"
  }'

Response
{
  "errors": []
}

Errors

Status	When
`200`	Success — check `errors` for validation messages (blank name/description on create, missing `versionToRollback`, MCP server unreachable).
`401`	The linked user lacks the required access level (see the access table), or is not the owner for `transfer-ownership`.
`403`	Scoped key without the endpoint in its allow-list.
`422`	`delete` refused because agents still use the tool; `errors` names them.
`408`	Server-side error; `errors` contains the message.

The tool object​

Versioning and access levels​

Create a tool​

Request parameters​

Response​

Get a tool​

Request parameters​

Response​

List all tools​

Request parameters​

Response​

Update a tool​

Request parameters​

Response​

Publish a tool​

Request parameters​

Response​

Roll back a tool​

Request parameters​

Response​

List versions​

Request parameters​

Response​

Create tools from an MCP server​

Request parameters​

Response​

Share a tool​

Request parameters​

Response​

Get sharing details​

Request parameters​

Response​

Delete a tool​

Request parameters​

Response​

Transfer ownership​

Request parameters​

Response​

Errors​

Related​

The tool object

Versioning and access levels

Create a tool

Request parameters

Response

Get a tool

Request parameters

Response

List all tools

Request parameters

Response

Update a tool

Request parameters

Response

Publish a tool

Request parameters

Response

Roll back a tool

Request parameters

Response

List versions

Request parameters

Response

Create tools from an MCP server

Request parameters

Response

Share a tool

Request parameters

Response

Get sharing details

Request parameters

Response

Delete a tool

Request parameters

Response

Transfer ownership

Request parameters

Response

Errors

Related