Skip to main content

Tools

A tool is a single capability an agent can call — send an email, query a table, scrape a page, run a script. Building one from the terminal is a four-step loop: create the draft, set its type and arguments, publish, then run it directly to check your work. Every command and response on this page is real output from a live session.

Key concepts​

Draft and published are different things​

A tool has a draft (your working copy) and a published version (what actually runs). create and update write the draft; publish snapshots it as a new live version.

A tool must be published before an agent, a scheduled job, or a table trigger can run it. A draft-only tool will attach fine and then fail at call time.

Publishing a tool does not attach it to an agent​

This is the single most common mistake. tools create + tools publish gives you a runnable tool that no agent knows about. Attaching is a separate step on the agent side — see Agents.

Prefer a purpose-built tool type over a script​

The platform ships hundreds of native tool types grouped by category — API_CALL and LLM_CALL as general building blocks, the AUTESSADB_* family for data, email and calendar types, media types, web types, MCP, and a large connector library. A native type arrives pre-wired with the right config fields and authentication.

AUTESSA_SCRIPT is the general-purpose escape hatch. A new draft tool starts as an AUTESSA_SCRIPT hello-world, which makes it tempting to just write code there. Resist that unless nothing fits — reach for a native type first.

How to pick a tool type​

Browse the catalog by category:

autessa tool-types categories
{
  "categories": [
    {
      "category": "platform",
      "title": "Platform",
      "description": "Autessa's own building blocks — the tool families that need no external connector.",
      "count": 28,
      "toolTypes": [
        "AUTESSA_SCRIPT", "API_CALL", "LLM_CALL", "SCHEDULE_EVENT",
        "AUTESSADB_INSERT", "AUTESSADB_UPDATE", "AUTESSADB_QUERY_TABLE",
        "AUTESSADB_SEMANTIC_QUERY", "MCP", "TRANSCRIBE", "SCRAPE_URL",
        "PERPLEXITY_SEARCH", "..."
      ]
    }
  ]
}

Then read one type's exact configuration fields, output shape and example:

autessa tool-types LLM_CALL
LLM Call  (LLM_CALL)

Sends promptTemplate — with its @@{...} placeholders already resolved — to a model as a single
prompt and returns the completion. model picks a capability tier by alias rather than a vendor model
name: SMALL_INSTRUCTION_FOLLOWING (the default), BIG_INSTRUCTION_FOLLOWING, [...]

*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *
  CONFIG (inputs)
*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *

  promptTemplate  <string>      Required string value.

  model           <object>      Required object value.

  timeoutSeconds  <integer>     Per-call timeout (seconds). Null = current default behavior (120s).

  [...]

*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *
  OUTPUT
*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *

  success  <boolean>     Whether the LLM call completed successfully
  content  <string>      The text content generated by the LLM
  usage    <object>      Token usage counts (promptTokens, completionTokens, totalTokens)

tool-types is a read-only reference surface — it does not create anything. The full catalog is also documented under Tool Types.

How to create and publish a tool​

1. Create the draft​

autessa tools create \
  --toolName "summarize_text" \
  --toolDescription "Summarizes a block of text in one sentence."
{
  "tool": {
    "toolId": "gPdJwp5jbr9eN",
    "companyId": "y8mRwXwboDVu",
    "toolConfig": {
      "toolType": "AUTESSA_SCRIPT",
      "config": {
        "script": "responseStream.addStreamMessage('Starting script execution');\nconsole.log(\"Hello world\")\n..."
      }
    },
    "name": "summarize_text",
    "description": "Summarizes a block of text in one sentence.",
    "arguments": {},
    "privateArguments": {},
    "tags": []
  }
}

Note the placeholder AUTESSA_SCRIPT config — that is the starting point, not the destination.

toolName is the function name the model sees, and toolDescription is what it reads to decide whether to call the tool. Write both for the model, not for a human browsing a list — precision here does more for reliability than anything in the agent's instructions.

2. Set its type and arguments​

tools update takes the complete desired configuration in --updatedTool, so read-modify-submit rather than sending a patch:

autessa tools update --toolId gPdJwp5jbr9eN --updatedTool '{
  "toolId": "gPdJwp5jbr9eN",
  "name": "summarize_text",
  "description": "Summarizes a block of text in one sentence.",
  "toolConfig": {
    "toolType": "LLM_CALL",
    "config": {
      "promptTemplate": "Summarize the following in exactly one sentence:\n\n@@{text}",
      "model": "SMALL_INSTRUCTION_FOLLOWING"
    }
  },
  "arguments": {
    "text": {
      "description": "The text to summarize.",
      "isRequired": true,
      "argumentSchema": { "type": "string" }
    }
  }
}'
{
  "updatedTool": {
    "toolId": "gPdJwp5jbr9eN",
    "toolConfig": {
      "toolType": "LLM_CALL",
      "config": {
        "promptTemplate": "Summarize the following in exactly one sentence:\n\n@@{text}",
        "model": "SMALL_INSTRUCTION_FOLLOWING"
      }
    },
    "name": "summarize_text",
    "description": "Summarizes a block of text in one sentence.",
    "arguments": {
      "text": {
        "description": "The text to summarize.",
        "isRequired": true,
        "argumentSchema": { "type": "string" }
      }
    },
    "tags": []
  }
}

Two details worth noting:

  • @@{name} placeholders in a tool's config are substituted from its arguments at run time. @@{text} in the prompt template is filled from the text argument.
  • Argument definitions normalize. The stored shape is isRequired and argumentSchema; the response tells you what was actually saved, so read it rather than assuming your input round-tripped verbatim.

3. Publish it​

autessa tools publish --toolId gPdJwp5jbr9eN
{ "publishedToolVersion": 1 }

4. Test it directly​

You can run a tool without an agent, which is the fastest way to check its configuration:

autessa tools execute --toolId gPdJwp5jbr9eN --variables '{
  "text": "The Autessa CLI is a model-driven command line interface generated from the live SDK manifest, so every command and flag is discovered rather than hand-maintained."
}'
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "summarize_text",
  "result": "{\"success\":true,\"content\":\"The Autessa CLI is dynamically generated from the live SDK manifest, allowing commands and flags to be discovered automatically instead of maintained manually.\",\"usage\":{\"promptTokens\":47,\"completionTokens\":44,\"totalTokens\":91}}",
  "invocationId": "df4fd983-9021-43c8-b42c-cb02c8f0105c"
}

--variables fills public arguments. Two related flags exist for values the model must never see:

  • --privateVariables — secrets and configuration declared as private arguments.
  • --environmentVariables — per-run values injected straight into tool execution, never declared to the model. See Environment variables.

Each execution bills one tool execution and is recorded in history.

How to import tools from an MCP server​

create-from-mcp bulk-creates tools from every tool a connected MCP server advertises:

autessa tools create-from-mcp --json '{...}'

Imported tools are tagged mcp plus the server host, so they are easy to find later with tools all. Connect and manage the servers themselves with the mcp namespace — see MCP servers.

How to read tool execution history​

autessa tools history list --toolId gPdJwp5jbr9eN
{
  "executions": [
    {
      "eventId": "a02e8438-9032-46f3-a875-41d051f2c013",
      "toolId": "gPdJwp5jbr9eN",
      "toolName": "summarize_text",
      "invocationId": "df4fd983-9021-43c8-b42c-cb02c8f0105c",
      "source": "API",
      "success": true,
      "durationMs": 3001,
      "createdAt": "2026-09-10T09:24:45Z",
      "requestVariables": "{\"text\":\"The Autessa CLI is a model-driven...\"}",
      "result": "{\"success\":true,\"content\":\"...\",\"usage\":{...}}",
      "requestTruncated": false,
      "resultTruncated": false
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "pageSize": 50,
  "hasNext": false,
  "hasPrevious": false
}

source tells you what triggered the run — API for a direct CLI call, plus AGENT, TRIGGER, SCHEDULED, WEBHOOK, WORK_ITEM and SCRIPT. It is the fastest way to tell a test run from production traffic.

Filter by outcome and page through results:

autessa tools history list --status error --page 0 --size 20
autessa tools history detail --eventId a02e8438-9032-46f3-a875-41d051f2c013

detail returns the full, uncapped request and result — reach for it whenever requestTruncated or resultTruncated is true.

How to version, share and delete​

autessa tools versions --toolId gPdJwp5jbr9eN
autessa tools rollback --toolId gPdJwp5jbr9eN --json '{...}'

versions lists the published version (null if never published) and every archived one; rollback re-publishes an archived version, archiving the current one in its place. See Versions.

autessa tools get-sharing-details --toolId gPdJwp5jbr9eN

# company-wide, read-only
autessa tools share --toolId gPdJwp5jbr9eN --level COMPANY --accessLevel READ

# or grant specific teammates
autessa tools share --toolId gPdJwp5jbr9eN --level SPECIFIC_MEMBER \
  --usersToAdd '[{"userEmail":"teammate@example.com","accessLevel":"WRITE"}]'

Sharing modes are PRIVATE, COMPANY at one access level, or SPECIFIC_MEMBER with per-user grants via usersToAdd/usersToRemove. Agents and tables share the same shape.

autessa tools delete --toolId gPdJwp5jbr9eN

Deletion is permanent — the draft and every version go with it. Agents still referencing the tool will fail at call time, so check tools all before removing something shared.

Next: give it to an agent​

A published tool does nothing on its own. Attach it to an agent and the model can call it:

autessa agents update --agentId K2UYSwk3Yy4i --updatedAgent '{
  "...": "...",
  "tools": [{ "toolId": "gPdJwp5jbr9eN" }]
}'

The full walkthrough — creating the agent, attaching tools, publishing, and running it one-shot or multi-turn — is in Agents.

Full command reference​

14 commands14 runnable
CommandWhat it does
autessa tools allList every tool you can access in the current company, split into three buckets — tools you own, tools shared company-wide, and tools shared specifically with you.
autessa tools createCreate a new bare draft tool with a name and description; set its type and configuration afterward with update.
autessa tools create-from-mcpBulk-create MCP tools by importing every tool advertised by a connected MCP server.
autessa tools deletePermanently delete a tool.
autessa tools executeRun a tool with the given input variables and return its structured result (bills one tool execution).
autessa tools getFetch a single tool by id, including its full configuration and your access level.
autessa tools get-sharing-detailsGet a tool's sharing configuration — sharing level, company-wide permission, per-user grants, and your own access level.
autessa tools history detailFetch one tool execution with its FULL (uncapped) decrypted request input and result output.
autessa tools history listList tool executions newest-first, scoped to your company, optionally filtered by tool and/or outcome, paginated.
autessa tools publishPublish the tool's current draft as a new live version — required before agents or scheduled events can run it.
autessa tools rollbackRe-publish a previously archived tool version, archiving the currently published version in its place.
autessa tools shareSet a tool's sharing mode — PRIVATE, COMPANY-wide at one access level, or SPECIFIC_MEMBER with per-user grants via usersToAdd/usersToRemove.
autessa tools updateUpdate a tool by submitting its full desired configuration in updatedTool.
autessa tools versionsList a tool's version numbers — the currently published version (null if never published) and all archived versions.