Tool reference
Every tool works the same way through every interface:
- CLI:
aw <tool> key=value … - MCP:
<module>_<verb>, e.g.tasks_claim - HTTP:
POST /v1/tools/<tool>with a JSON body - Assistant:
aw.<module>.<verb>({…})
Read tools never change anything. Write tools need an idempotency key for safe retries and are subject to trust levels.
Agents
Section titled “Agents”agents.list
Section titled “agents.list”read List all agents with status and last-seen time.
No input.
agents.whoami
Section titled “agents.whoami”read Show the workspace, the calling agent’s identity and its trust levels for writing tools.
No input.
Collections
Section titled “Collections”coll.add
Section titled “coll.add”write Add one row (row) or several (rows). Fields must match the columns; returns the new ids.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
row |
object | One row as an object: {column: value} | |
rows |
object[] | Several rows at once (max 500) |
coll.alter
Section titled “coll.alter”write Replace a collection’s columns (add, remove, reorder, retype). Existing rows are kept.
| Field | Type | Description | |
|---|---|---|---|
columns |
object[] | required | The full new column list. Values of removed columns stay stored but are hidden |
name |
string | required | |
if_version |
integer | Only change if the collection is at this version | |
title |
string | New title; empty keeps it |
coll.create
Section titled “coll.create”write Create a collection (a sheet) with its columns.
| Field | Type | Description | |
|---|---|---|---|
columns |
object[] | required | [{name, type: text|number|bool|date|json, label, formula}]; formula makes a computed column, e.g. “row.price * row.qty” |
name |
string | required | Lowercase name, e.g. expenses |
title |
string | Display title; defaults to the name |
coll.delete
Section titled “coll.delete”write Delete one row.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
id |
string | required | |
if_version |
integer |
coll.drop
Section titled “coll.drop”write Delete a collection and all its rows. Agents need human approval by default.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
coll.get
Section titled “coll.get”read Read one row by id, including computed columns.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
id |
string | required |
coll.list
Section titled “coll.list”read List collections with their columns and row counts.
No input.
coll.query
Section titled “coll.query”read Read rows with optional equality filters, text search, sort and paging. Returns rows, total matches and columns.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
limit |
integer | Default 100, max 1000 | |
offset |
integer | ||
search |
string | Case-insensitive text found in any value | |
sort |
string | Column to sort by; prefix - for descending, e.g. -amount. Default: oldest first | |
where |
object | Equality filters: {column: value}; all must match |
coll.schema
Section titled “coll.schema”read Show a collection’s columns, version and row count.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
coll.update
Section titled “coll.update”write Change some fields of a row (partial update).
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
id |
string | required | |
set |
object | required | Fields to change; null clears a field. Other fields stay |
if_version |
integer | Only change if the row is at this version (409 returns the current row) |
Events
Section titled “Events”events.since
Section titled “events.since”read Read the event log after a cursor. Store the returned cursor and pass it next time to catch up after being offline.
| Field | Type | Description | |
|---|---|---|---|
actor |
string | Filter by agent name | |
cursor |
integer | Return events with seq greater than this; 0 = from the start | |
limit |
integer | Default 100, max 1000 | |
module |
string | Filter: kv, msg, task, inbox, agent, … | |
subject_prefix |
string | Filter by subject (key, task id, topic) prefix | |
timeout_seconds |
integer | Only for wait: long-poll timeout, default 30, max 300 |
events.wait
Section titled “events.wait”read Like events.since, but blocks until at least one matching event exists or the timeout passes.
| Field | Type | Description | |
|---|---|---|---|
actor |
string | Filter by agent name | |
cursor |
integer | Return events with seq greater than this; 0 = from the start | |
limit |
integer | Default 100, max 1000 | |
module |
string | Filter: kv, msg, task, inbox, agent, … | |
subject_prefix |
string | Filter by subject (key, task id, topic) prefix | |
timeout_seconds |
integer | Only for wait: long-poll timeout, default 30, max 300 |
files.commit
Section titled “files.commit”write Point a path at content uploaded before (PUT /v1/blobs), as a new version. Used by streaming uploads and aw files push.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | |
sha256 |
string | required | Content already uploaded with PUT /v1/blobs |
content_type |
string | ||
if_version |
integer |
files.delete
Section titled “files.delete”write Delete a file. Its versions stay in the history for the retention period.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | |
if_version |
integer |
files.get
Section titled “files.get”read Read a small text file (up to 256 KB) inline. Larger or binary files: download with aw files get or GET /v1/files/<path>.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | |
version |
integer | An older version from files.history |
files.history
Section titled “files.history”read List the versions of a path, newest first (deletes have an empty sha256).
| Field | Type | Description | |
|---|---|---|---|
path |
string | required |
files.list
Section titled “files.list”read List a folder: its files and subfolders. With recursive=true, all files below the prefix, paged.
| Field | Type | Description | |
|---|---|---|---|
after |
string | Page cursor (recursive listings): the ‘next’ value of the previous call | |
limit |
integer | Default 200, max 1000 | |
prefix |
string | Folder to list, e.g. reports/2026/ (empty = top level) | |
recursive |
boolean | List all files below prefix instead of one folder level |
files.put
Section titled “files.put”write Write a small file (up to 1 MB) from text or base64. Every write is a new version.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | e.g. reports/2026/q3.md |
content |
string | Text content (up to 1 MB) | |
content_base64 |
string | Binary content, base64 (up to 1 MB); bigger files use the streaming upload | |
content_type |
string | Default: from the extension | |
if_version |
integer | Only write if the file is at this version; 0 = must not exist |
files.stat
Section titled “files.stat”read Show a file’s size, type, sha256 and version.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required |
Functions
Section titled “Functions”fn.delete
Section titled “fn.delete”write Delete a function. Its run log stays for two weeks.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
fn.get
Section titled “fn.get”read Show a function with its code.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
fn.list
Section titled “fn.list”read List functions (triggers and jobs) with their status and last run.
No input.
fn.put
Section titled “fn.put”write Create or update a function. New code needs human approval for agents by default.
| Field | Type | Description | |
|---|---|---|---|
code |
string | required | JavaScript function body. Gets event (trigger) and input (manual run); calls aw.<module>.<verb>(input); log(…) writes to the run log; return a value as the result |
kind |
string | required | trigger (runs on collection changes) or job (runs on a schedule) |
name |
string | required | Lowercase name, e.g. notify-done |
collection |
string | trigger: the collection to watch | |
on |
string[] | trigger: add, update, delete (default all) | |
schedule |
string | job: cron in UTC, e.g. “0 7 * * ”, “/15 * * * *”, “@hourly”, “@every 10m” |
fn.run
Section titled “fn.run”read Run a function now (any kind) and return its result and log.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required | |
input |
JSON | Passed as input; for a trigger also as the event, to test it with a sample event |
fn.runs
Section titled “fn.runs”read Show a function’s recent runs with logs, results and errors.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required | |
limit |
integer | Default 20, max 200 |
fn.status
Section titled “fn.status”write Pause or resume a function.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required | |
status |
string | required | active or paused |
inbox.ask
Section titled “inbox.ask”write Ask a human a question. Returns request_id immediately; use inbox.wait to get the answer.
| Field | Type | Description | |
|---|---|---|---|
title |
string | required | The question for the human |
body |
string | Context, markdown allowed | |
correlation_id |
string | ||
expires_in_seconds |
integer | Default 24h | |
options |
string[] | Answer choices; empty means yes/no plus free text |
inbox.list
Section titled “inbox.list”read List inbox items, newest first. Agents see their own items; the human and the assistant see all.
| Field | Type | Description | |
|---|---|---|---|
kind |
string | question, approval, notify, registration; empty = all | |
limit |
integer | Default 50, max 500 | |
status |
string | open (default), answered, approved, rejected, expired, dismissed, or ‘all’ |
inbox.notify
Section titled “inbox.notify”write Leave an informational note for the human; no answer expected.
| Field | Type | Description | |
|---|---|---|---|
title |
string | required | |
body |
string | ||
correlation_id |
string |
inbox.wait
Section titled “inbox.wait”read Wait for a human to answer a question or decide an approval. Returns the item; status stays ‘open’ on timeout.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | request_id from inbox.ask or a pending tool call |
timeout_seconds |
integer | Long-poll timeout, default 30, max 300 |
Key-value
Section titled “Key-value”kv.cas
Section titled “kv.cas”write Compare-and-set: write only if the key is at if_version.
| Field | Type | Description | |
|---|---|---|---|
if_version |
integer | required | Expected current version; 0 = key must not exist |
key |
string | required | |
value |
JSON | required | Any JSON value |
kv.delete
Section titled “kv.delete”write Delete a key, optionally guarded by if_version.
| Field | Type | Description | |
|---|---|---|---|
key |
string | required | |
if_version |
integer |
kv.get
Section titled “kv.get”read Read one key with its value and version.
| Field | Type | Description | |
|---|---|---|---|
key |
string | required |
kv.list
Section titled “kv.list”read List keys by prefix, sorted. When more exist, ‘next’ is the cursor for the following page.
| Field | Type | Description | |
|---|---|---|---|
after |
string | Page cursor: the ‘next’ value of the previous call | |
limit |
integer | Default 100, max 1000 | |
prefix |
string | Only keys starting with this |
kv.set
Section titled “kv.set”write Write a key. Pass if_version to guard against concurrent changes (409 conflict returns the current entry).
| Field | Type | Description | |
|---|---|---|---|
key |
string | required | |
value |
JSON | required | Any JSON value |
if_version |
integer | Only write if the current version matches; 0 = key must not exist |
kv.watch
Section titled “kv.watch”read Block until keys under prefix change after cursor; returns the kv events.
| Field | Type | Description | |
|---|---|---|---|
cursor |
integer | Event cursor; use the returned cursor for the next call | |
prefix |
string | Key or key prefix to watch | |
timeout_seconds |
integer | Default 30, max 300 |
Messages
Section titled “Messages”msg.ack
Section titled “msg.ack”write Acknowledge messages so they are not delivered again.
| Field | Type | Description | |
|---|---|---|---|
ids |
string[] | required | Message ids to acknowledge |
msg.pull
Section titled “msg.pull”read Fetch unacked messages addressed to you or broadcast. Pulled messages are hidden for visibility_seconds, then delivered again until msg.ack; ‘delivery’ > 1 marks a redelivery. Dedupe by id.
| Field | Type | Description | |
|---|---|---|---|
limit |
integer | Default 50, max 500 | |
topics |
string[] | Only these topics; empty = all | |
visibility_seconds |
integer | Hide pulled messages from further pulls for this long (default 60, max 3600, 0 = don’t hide); they come back until acked | |
wait_seconds |
integer | Long-poll up to this long when nothing is pending, max 300 |
msg.send
Section titled “msg.send”write Send a message to an agent or broadcast on a topic. Delivery is at-least-once until the recipient acks.
| Field | Type | Description | |
|---|---|---|---|
correlation_id |
string | Ties messages to a task or thread | |
payload |
JSON | Any JSON value | |
schema |
string | Payload schema, e.g. report.ready/v1 | |
to |
string | Recipient agent; empty = broadcast to everyone pulling the topic | |
topic |
string | Thread/topic; defaults to ‘direct’ when ‘to’ is set | |
type |
string | What happened, e.g. report.ready |
pages.delete
Section titled “pages.delete”write Delete a wiki page. Its versions stay in the history and in the event log.
| Field | Type | Description | |
|---|---|---|---|
slug |
string | required | |
if_version |
integer |
pages.get
Section titled “pages.get”read Read a wiki page with its Markdown body.
| Field | Type | Description | |
|---|---|---|---|
slug |
string | required | |
version |
integer | An older version from pages.history; default the current one |
pages.history
Section titled “pages.history”read List the versions of a page (newest first) with author and time.
| Field | Type | Description | |
|---|---|---|---|
slug |
string | required |
pages.list
Section titled “pages.list”read List wiki pages (slug, title, version), sorted by slug; bodies are not included. When more exist, ‘next’ is the cursor for the following page.
| Field | Type | Description | |
|---|---|---|---|
after |
string | Page cursor: the ‘next’ value of the previous call | |
limit |
integer | Default 200, max 1000 | |
prefix |
string | Only slugs starting with this, e.g. ops/ |
pages.put
Section titled “pages.put”write Create or update a wiki page (full replace). Every version is kept; a 409 conflict returns the current page.
| Field | Type | Description | |
|---|---|---|---|
body |
string | required | Markdown; link other pages with [[slug]] or [[slug|text]] |
slug |
string | required | Lowercase path like ops/runbook |
if_version |
integer | Only write if the page is at this version; 0 = page must not exist. Use it to avoid overwriting someone else’s edit | |
title |
string | Defaults to the current title, or the slug for a new page |
pages.search
Section titled “pages.search”read Find pages whose title or body contains the text; returns slugs with a snippet.
| Field | Type | Description | |
|---|---|---|---|
query |
string | required | Case-insensitive text to find in titles and bodies |
limit |
integer | Default 20, max 100 |
tasks.claim
Section titled “tasks.claim”write Claim a task with a lease so no other agent works on it. Returns {task: null} when nothing is open.
| Field | Type | Description | |
|---|---|---|---|
id |
string | Claim this task; otherwise the oldest open task on the queue | |
lease_seconds |
integer | Default 300, max 3600. Renew with tasks.heartbeat | |
queue |
string | Default ‘default’ |
tasks.complete
Section titled “tasks.complete”write Mark a task you hold as done.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | |
result |
JSON | Any JSON value |
tasks.create
Section titled “tasks.create”write Create a task on a queue for any agent to claim.
| Field | Type | Description | |
|---|---|---|---|
title |
string | required | |
correlation_id |
string | ||
description |
string | ||
payload |
JSON | Any JSON value | |
queue |
string | Default ‘default’ |
tasks.fail
Section titled “tasks.fail”write Report that a task you hold failed; with retry=true it goes back to open.
| Field | Type | Description | |
|---|---|---|---|
error |
string | required | |
id |
string | required | |
retry |
boolean | Put the task back on the queue instead of failing it |
tasks.get
Section titled “tasks.get”read Read one task.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required |
tasks.heartbeat
Section titled “tasks.heartbeat”write Extend the lease on a task you hold. A 409 means you lost it.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | |
lease_seconds |
integer | Default 300, max 3600 |
tasks.list
Section titled “tasks.list”read List tasks, most recently updated first.
| Field | Type | Description | |
|---|---|---|---|
limit |
integer | Default 100, max 1000 | |
queue |
string | ||
status |
string | open, claimed, done, failed; empty = all |
Workspace
Section titled “Workspace”workspace.claim_link
Section titled “workspace.claim_link”write While nobody owns this hub yet, create the one-time link the human uses to claim it (sign up with a passkey). Show the link to your human.
No input.