autessa.tools
Create tools of any type and execute them.
autessa.tools.allREAD
autessa.tools.all()List every tool you can access in the current company, split into owned, company-shared, and shared-with-me.
Returns your accessible tools in three buckets. Not paginated. Each tool includes its full configuration (name, description, type, arguments).
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
ownedTools- Type
- AutessaTool[]
- Description
- Name
companySharedTools- Type
- AutessaTool[]
- Description
- Name
sharedWithMeTools- Type
- AutessaTool[]
- Description
autessa.tools.createMUTATE
autessa.tools.create({ toolName, toolDescription })Create a new draft tool with a name and description; set its type and configuration afterward with tools.update.
Creates a bare draft tool. Both toolName and toolDescription are required and must be non-blank (a blank one returns an error, not success). The new tool has no type or arguments yet — call tools.update with a full AutessaTool to configure it, then tools.publish to make it runnable.
Request fields
- Name
toolName- Type
- string
- Description
- Name
toolDescription- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
tool- Type
- AutessaTool
- Description
autessa.tools.createFromMcpMUTATE
autessa.tools.createFromMcp({ mcpServerId })Bulk-create MCP tools by importing every tool advertised by a connected MCP server.
Connects to the given MCP server, lists its advertised tools, and creates one draft AutessaTool per advertised tool — each of type MCP, with arguments parsed from the tool's JSON-schema and tagged mcp plus the server host. Tools that fail to import are skipped; if none succeed (or the server has no tools / is unreachable) an error is returned. The created tools are drafts — publish each before use.
Request fields
- Name
mcpServerId- Type
- string (opaque id)
- Description
- References mcp server by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
createdTools- Type
- AutessaTool[]
- Description
autessa.tools.deleteMUTATE
autessa.tools.delete({ toolId })Permanently delete a tool, unless an agent still uses it.
Irreversible; requires ADMIN access. The delete is blocked (returns an error listing the agents by name) if any agent still references this tool — remove all such usages first.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
autessa.tools.executeMUTATE
autessa.tools.execute({ toolId, environmentVariables, privateVariables, variables, autessaTool })Run a tool with the given input variables and return its structured result (bills one tool execution).
Executes the published tool identified by toolId as YOU (your identity governs AutessaDB row/column security). Supply public inputs in variables, secret inputs in privateVariables, and tool environment in environmentVariables. Subject to per-company tool-execution rate limits (a 429 with errors ['Rate limit exceeded'] when exceeded). The tool's structured output is in result; any tool-emitted public variables are in publicVars. Use this to TEST a tool you just built: run it with representative variables and inspect result — this is how you confirm every @@{argument} you referenced in the config is actually declared and resolves (an undeclared/misspelled argument is left unsubstituted, so the only reliable way to catch it is to execute and look at the output). Iterate tools.update → tools.publish → tools.execute until the result is correct before wiring the tool onto an agent.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
- Name
environmentVariables- Type
- object
- Description
- Name
privateVariables- Type
- object
- Description
- Name
variables- Type
- object
- Description
- Name
autessaTool- Type
- AutessaTool
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
responseType- Type
- string
- Description
- Name
toolName- Type
- string
- Description
- Name
publicVars- Type
- object
- Description
- Name
result- Type
- object
- Description
- Name
debuggingInfo- Type
- object
- Description
- Name
streamMessage- Type
- string
- Description
- Name
invocationId- Type
- string
- Description
autessa.tools.getREAD
autessa.tools.get({ toolId, version })Fetch a single tool by id, including its full configuration and your access level.
Returns the tool entity and your permission on it. Pass version to read a specific published or archived version instead of the current draft.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
- Name
version- Type
- CustomVersion
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
permission- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
- Name
tool- Type
- AutessaTool
- Description
autessa.tools.getSharingDetailsREAD
autessa.tools.getSharingDetails({ toolId })Get a tool's sharing configuration: sharing level, company-wide permission, per-user grants, and your own access level.
Read-only view of exactly what tools.share would modify. Returns an error if you have no access to the tool.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
sharingLevel- Type
- "PRIVATE" | "SPECIFIC_MEMBER" | "COMPANY"
- Description
- Name
companyPermissionLevel- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
- Name
sharedWith- Type
- UserShareWrapper[]
- Description
- Name
userAccessLevel- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
autessa.tools.publishMUTATE
autessa.tools.publish({ toolId })Publish the tool's current draft configuration as a new live version.
Snapshots the draft into a new immutable, published version — required before the tool can be run by agents or scheduled events. Requires PUBLISH or ADMIN access. Returns the new published version number.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
publishedToolVersion- Type
- number
- Description
autessa.tools.rollbackMUTATE
autessa.tools.rollback({ toolId, versionToRollback })Re-publish a previously archived tool version, archiving the currently published version in its place.
versionToRollback is required and must be an archived version number from tools.versions. This swaps versions rather than minting a new one; the unpublished draft is untouched. Requires PUBLISH or ADMIN access.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
- Name
versionToRollback- Type
- number
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
newPublishedVersion- Type
- number
- Description
autessa.tools.updateMUTATE
autessa.tools.update({ toolId, updatedTool })Update a tool by submitting its modified configuration in updatedTool (read with tools.get, modify, submit).
Your updatedTool is merged over the stored tool, not swapped for it: fields you do not mention — and config keys you do not mention — survive from the stored tool. So the safe pattern is always read-modify-submit: start from the entity returned by tools.get, change what you want, and submit. To send a new value for a nested config key while leaving its siblings untouched, include just that key. To DELETE a config key, or to replace the whole tool with exactly your body (nothing merged in), pass { replace: true } as the second argument: autessa.tools.update({ toolId, updatedTool }, { replace: true }). At save, any config key that is not valid for the tool's type is dropped silently — a leftover key from a previous tool type will not block the update, so you do not need to strip it yourself. Requires WRITE, PUBLISH, or ADMIN access. This is where a tool's type and type-specific config are set. Changes affect the draft only until you call tools.publish. ARGUMENTS: every entry you add to updatedTool.arguments (or privateArguments) MUST be a full object with description (string), isRequired (boolean), and argumentSchema (a JSON-schema object containing a type). An argument written as just { description } has no argumentSchema and breaks the tool's UI view and its runtime — always set argumentSchema.type (use "string" when unsure).
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
- Name
updatedTool- Type
- AutessaTool
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
updatedTool- Type
- AutessaTool
- Description
autessa.tools.versionsREAD
autessa.tools.versions({ toolId })List a tool's version numbers: the currently published version (null if never published) and all archived versions.
Use archivedVersions with tools.rollback to re-publish an older version.
Request fields
- Name
toolId- Type
- string (opaque id)
- Description
- References tool by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
currentPublishedVersion- Type
- number
- Description
- Name
archivedVersions- Type
- number[]
- Description