arizuko › reference › MCP tools

MCP tools reference

Every Model Context Protocol tool the arizuko platform registers on a per-group unix socket. Generated from ipc/ipc.go and ipc/inspect.go. The tool set a given session sees is filtered by grants.MatchingRules against the group's rule list — tools whose name doesn't match any rule are not registered. A handful of tools also gate registration on tier (e.g. list_acl is tier 0–1; get_web_presence is tier 0–1).

Contents

messages

post tier 0–2

Create a new top-level post on a platform (mastodon toot, bluesky post, discord channel message, reddit submission). Use for broadcast/announcement content that isn't replying to anyone. Not for replies (reply), direct messages (send), or file delivery (send_file).

Source: ipc/ipc.go:1052 · Grant action: post(jid=...) · REST twin: POST /v1/turns/{turn_id}/post.

Returns: JSON {"ok": true, "id": "<platformId>"}; on adapter "unsupported", returns error text with platform hint.

reply

The default way to respond — use for virtually every answer to the user. Delivers a message threaded to the conversation (quote/reply UI on the platform; on Slack it lands in the thread, not the channel root). Omit replyToId to thread to the current conversation automatically, or pass it to target a specific earlier message. Only reach for send when you deliberately need a fresh top-level message that is NOT a reply.

Source: ipc/ipc.go:928 · Grant action: reply(jid=...) · In basicSendActions at every tier ≥ 1.

Returns: text "ok"; outbound recorded into messages with the returned platform id.

send

Deliver a fresh top-level message that is NOT a reply to the current conversation. Use ONLY when you explicitly need that — a proactive/unprompted notification, or a message to a different chat. For responding to the user (the normal case) use reply, which threads. Not for threaded replies (reply) or file delivery (send_file — its caption replaces this call).

Source: ipc/ipc.go:900 · Grant action: send(jid=...) · In basicSendActions at every tier ≥ 1.

Returns: text "ok"; outbound recorded into messages with the platform-returned id.

send_file

Deliver a file from the group workspace (~/) to a chat. Works on every platform whose channel registered the tool. The caption IS the accompanying message — never follow with send. Not for inline text the user can read in-chat.

Source: ipc/ipc.go:964 · Grant action: send_file(jid=...) · Path validated via mountsec.ValidateFilePath.

Returns: text "ok".

send_voice

Deliver text as a synthesized voice message on the platform — push-to-talk on Telegram/WhatsApp, audio attachment on Discord. voice defaults to PERSONA.md frontmatter or the instance default; pass an explicit name to override.

Source: ipc/ipc.go:1009 · Grant action: send_voice(jid=...) · Max 5000 chars; requires TTS_BASE_URL (otherwise UnsupportedError propagates). REST twin: POST /v1/turns/{turn_id}/send_voice.

Returns: JSON {"ok": true, "id": "<platformId>"}; on adapter unsupported, error text with platform hint.

social actions

All registered via the regSocial/socialAct helper at ipc/ipc.go:1114. All take string args; the first arg (or jidArg) is grant-checked + folder-authorized. All adapter errors are rendered through toolMaybeUnsupported, surfacing the platform hint to the agent.

delete

Delete a post/message previously created by this agent (platform enforces authorship). Use to retract an incorrect or superseded post. No edit tool — delete and re-post.

Source: ipc/ipc.go:1171 · Grant action: delete(jid=...)

Returns: text "ok".

dislike

Endorse-negative on a message (Discord 👎 reaction). Native only — Mastodon, Bluesky, and most platforms have no native downvote and return unsupported with a hint.

Source: ipc/ipc.go:1226 · Grant action: dislike(jid=...) · See user-pref: on emoji-reaction platforms, prefer like(reaction='👎').

Returns: text "ok".

edit

Modify a message previously sent by this agent in-place (Discord, Mastodon, Bluesky, Telegram own bot messages). Preserves the platform message id. Email is unsupported.

Source: ipc/ipc.go:1238 · Grant action: edit(jid=...)

Returns: text "ok".

forward

Redeliver an existing message to a different chat with provenance preserved (Telegram forward, WhatsApp forward, email Fwd:). Not for replying within the same chat (reply) or amplifying on a public feed (repost / quote).

Source: ipc/ipc.go:1183 · Grant action: forward(jid=<targetJid>) — jidArg is targetJid, not the source. REST twin: POST /v1/turns/{turn_id}/forward.

Returns: JSON {"ok": true, "id": "<platformId>"}.

like

Like an existing message (unicode emoji on Discord, favourite on Mastodon, like on Bluesky). Use when acknowledging or endorsing a specific earlier message without sending text. Platform decides what reaction strings are valid; unsupported platforms return an error.

Source: ipc/ipc.go:1159 · Grant action: like(jid=...)

Returns: text "ok".

quote

Republish a message on your own feed with added commentary (Bluesky quote, X quote-tweet). Native only — Mastodon has no quote primitive and returns unsupported with a hint to use post(content=..., source_url=...).

Source: ipc/ipc.go:1198 · Grant action: quote(jid=...) · REST twin: POST /v1/turns/{turn_id}/quote.

Returns: JSON {"ok": true, "id": "<platformId>"}.

repost

Amplify a message on your own feed without added text (Mastodon boost, Bluesky repost, X retweet). Use to endorse-and-share. Not for commentary (quote) or sending a copy to a different chat (forward).

Source: ipc/ipc.go:1212 · Grant action: repost(jid=...) · REST twin: POST /v1/turns/{turn_id}/repost.

Returns: JSON {"ok": true, "id": "<platformId>"}.

pin_message

Pin a message to a chat/channel (Slack pins.add, Discord channel pin, Telegram pinned message). Use to mark a live status surface (deploy progress, standup link) or anchor a reference. Targets any message in the chat — not author-scoped like edit/delete. Mastodon, Bluesky, Reddit, email, WhatsApp return unsupported.

Source: ipc/ipc.go:1250 · Grant action: pin_message(jid=...)

Returns: text "ok".

unpin_message

Remove the pin on a specific message (Slack pins.remove, Discord channel unpin, Telegram unpinChatMessage). Use to retire a status surface or rotate the pinned reference. Not for clearing every pin (unpin_all) or deleting the message (delete).

Source: ipc/ipc.go:1262 · Grant action: unpin_message(jid=...)

Returns: text "ok".

unpin_all

Clear every pin in a chat/channel (Slack iterates pins.list + pins.remove; Telegram unpinAllChatMessages). Use when wholesale resetting a channel's pinned set. Discord has no bulk primitive — call unpin_message per id.

Source: ipc/ipc.go:1274 · Grant action: unpin_all(jid=...)

Returns: text "ok".

history & inspection

fetch_history

Pull authoritative conversation history from the channel adapter and cache it. Use to reconstruct context before replying, especially on first contact or after a reset_session. Falls back to local cache if the adapter is down. Not for DB/routing audits (inspect_messages) or single-thread slices (get_thread).

Source: ipc/ipc.go:2536 · Registered only when gated.FetchPlatformHistory != nil. Tier > 0 callers must have the JID routed to their folder.

Returns: JSON {messages, count, oldest, source, cap}. source is platform / platform-capped / cache-only / unsupported / cache; messages rendered by router.FormatMessages.

get_thread

Return rows from local messages.db scoped to one thread (chat_jid + topic). Use when a chat fans out into per-topic conversations (Telegram forum topics, web-chat topics).

Source: ipc/ipc.go:2492 · Registered only when db.MessagesByThread != nil.

Returns: JSON {messages, count, oldest, source:"local-db"}.

inspect_messages

Return rows from the local messages.db for one chat_jid, including outbound/bot rows and errored entries. Use for routing/delivery audits or to verify what the store recorded.

Source: ipc/ipc.go:2407 · Registered only when db.MessagesBefore != nil.

Returns: JSON {messages, count, oldest, source:"local-db"}.

find_messages

Full-text search over local messages.db using SQLite FTS5. query takes FTS5 syntax — a bare token, a "quoted phrase", a OR b, a NOT b, prefix*, or NEAR(a b, 5). Use to find a past message by what it said. Not for whole-chat scroll (inspect_messages), single-thread slices (get_thread), or platform-truth fallback (fetch_history).

Source: ipc/ipc.go:2422 · Registered only when db.FindMessages != nil. Tier > 0 callers see only rows whose chat_jid is routed to their folder (post-fetch ACL via db.JIDRoutedToFolder); tier 0 bypasses. Backed by the messages_fts shadow table (migration 0070).

Returns: JSON {messages, count, source:"local-db"}. Each row carries chat_jid, sender, timestamp, content (a snippet() fragment with «» around the hit, not the full body), and rank (BM25 — lower is a better match). Ordered by rank, then newest first.

inspect_routing

Return routes visible to this group plus the errored-chat aggregate; pass jid to also resolve that JID to its folder. Use when a message isn't reaching the expected group, or to triage delivery failures.

Source: ipc/inspect.go:15 · Registered only when db.ListRoutes and db.DefaultFolderForJID are set.

Returns: JSON {routes, errored?, jid?, resolved_folder?}.

inspect_session

Return current session_id for this group/topic plus recent session_log rows (message counts, last error, last reset). Use to check whether context is healthy. Not for clearing state (reset_session).

Source: ipc/inspect.go:77 · Registered only when db.GetSession and db.RecentSessions are set.

Returns: JSON {folder, topic, session_id, recent}.

inspect_tasks

Return tasks visible to this group; pass task_id for that task's recent run logs (durations, errors). Use to debug why a scheduled prompt didn't fire or failed.

Source: ipc/inspect.go:49 · Registered only when db.ListTasks != nil. Non-root callers gated by auth.Authorize on the task's owner folder.

Returns: JSON {tasks, runs?}.

groups & delegation

delegate_group tier 0–1

Hand a prompt down to a specific child group for async execution; the child runs in its own session and workspace. Depth capped at 1.

Source: ipc/ipc.go:1792 · Grant action: delegate_group (in tier1FixedActions) · auth.Authorize on the target folder.

Returns: JSON {"queued": true}; enqueues a message-check for the target.

escalate_group tier 0–1

Hand a prompt up to this group's parent folder; the parent responds back through this child. Use when the request exceeds this group's authority or needs operator review. Depth capped at 1.

Source: ipc/ipc.go:1724 · Grant action: escalate_group (in tier1FixedActions) · Wraps the prompt in <escalation_origin/> with reply_to provenance.

Returns: JSON {"queued": true, "parent": "<folder>"}.

refresh_groups tier 0–2

Return folder/name/parent for every registered group. Use to discover delegation targets or audit the group tree.

Source: ipc/ipc.go:1774 · Registration gated on id.Tier ≤ 2; bypasses the grant-rule filter.

Params: none. Returns: JSON array of {folder, name, parent?}.

register_group tier 0–1

Create a child agent group and route a JID to it. Use when onboarding a new chat into its own isolated workspace, or when spinning up a sub-agent from this group's prototype/ (fromPrototype=true).

Source: ipc/ipc.go:1657 · Grant action: register_group (in tier1FixedActions) · auth.CheckSpawnAllowed enforces spawn quota when registering manually.

Returns: JSON {"registered": true, "folder": "<f>", "jid": "<jid>"}; SetupGroup seeds skills/settings/tasks.

set_group_open tier 0–1

Toggle this group's visibility to sibling folders. When open=true, sibling folders' ambient messages surface in this group's <observed> block (and this group's messages surface to open siblings). Default: open. Use to seal off a sensitive folder from cross-folder ambient context. Spec: 7/F. Concept: scopes.

Source: ipc/ipc.go:1531 · Grant action: set_group_open · auth.AuthorizeStructural on the calling folder.

Returns: JSON {"ok": true, "open": <bool>}.

set_observe_window

Override this group's ambient observe-window caps (messages and/or chars). Per-group caps win over instance env defaults (OBSERVE_WINDOW_MESSAGES, OBSERVE_WINDOW_CHARS); per-route caps still win over both. Pass -1 to clear an override; omit a field to leave it unchanged. Spec: 7/F.

Source: ipc/ipc.go:1485 · Grant action: set_observe_window.

Returns: JSON {"ok": true, "messages": <n>, "chars": <n>}.

sessions & work

get_work

Read this group's work.md — current work, blockers, next steps. Use at the start of a turn to recover what was in-flight. Returns empty content when the file doesn't exist.

Source: ipc/ipc.go:2610 · Unconditionally registered; not grant-filtered.

Params: none. Returns: JSON {content, exists}.

inject_message

Write a synthetic inbound message into the store as if received from chat, triggering the normal agent loop. Use for programmatic prompts, tests, or scheduling one-off runs from tool code.

Source: ipc/ipc.go:1623 · Grant action: inject_message

Returns: JSON {"injected": true, "id": "<mid>"}.

fork_topic

Branch a topic from another’s current state. The gateway copies the parent’s Claude Code session file to a fresh session_id, so the child resumes natively with the parent’s history already in its session — no prompt-injection block. Use when starting a focused side-conversation that needs the parent’s recent state but should not pollute it. Pass force=true to overwrite an existing child. Spec: 7/F.

Source: ipc/ipc.go · Grant action: fork_topic · auth.AuthorizeStructural on caller’s folder.

Returns: JSON {"folder", "parent_topic", "child_topic"}. Error "topic_exists" when child exists and force=false.

pane_set_prompts

Slack only — stage suggested-prompt buttons shown at the bottom of the assistant pane after your next reply lands. Fire-and-forget; the buttons appear once and persist until your next call. Use after a reply when you can anticipate the user’s likely follow-ups (e.g. “dig deeper”, “summarise”, “export”). 3-4 prompts is the visible cap. Adapters without pane semantics return chanlib.ErrUnsupported. Spec: 7/D. Concept: slack pane.

Source: ipc/ipc.go:1286 · Grant action: pane_set_prompts.

Returns: text "ok".

pane_set_title

Slack only — override the title shown at the top of the assistant pane. Fires after your next reply lands. Use to reflect the active topic (e.g. “atlas — debugging the build”). Defaults to <assistant> — chat when never set. Spec: 7/D.

Source: ipc/ipc.go:1316 · Grant action: pane_set_title.

Returns: text "ok".

engage

Mark (jid, topic) engaged for the ENGAGEMENT_TTL window so subsequent inbounds fire even when the route table wouldn't route them here. Use before a scheduled or autonomous turn, or to recover after a failed reply. Caller folder must already own the conversation (last reply here, or default route here). Spec: 5/G.

Source: ipc/ipc.go:1413 · Grant action: engage.

Returns: JSON {"ok": true}.

disengage

Clear engagement for (jid, topic). Subsequent inbounds need a fresh mention to re-fire. Use when the bot is done helping or when a corrective fork is closing. Caller folder must own the conversation. Spec: 5/G.

Source: ipc/ipc.go:1440 · Grant action: disengage.

Returns: JSON {"ok": true}.

reset_session

Drop the Claude session for a group so the next message starts fresh context. Use when the user asks for /new, when context is confused/polluted, or before a topic switch. Not for injecting content (inject_message).

Source: ipc/ipc.go:1464 · Grant action: reset_session · auth.Authorize on target folder.

Returns: text "ok".

set_work tier 0–2

Overwrite this group's work.md with a fresh snapshot of current work, blockers, and next steps. Use at turn end to checkpoint state. This replaces the file — read with get_work first if merging.

Source: ipc/ipc.go:2627 · Registration gated on id.Tier ≤ 2. Atomic rename via .tmp.

Returns: text "ok".

scheduling

cancel_task tier 0–1

Permanently delete a scheduled task. Use when the task is no longer wanted. Not for temporary suspension (pause_task) — this cannot be undone.

Source: ipc/ipc.go:2117 · Grant action: cancel_task (in tier1FixedActions) · auth.Authorize on the task's owner folder. REST twin: DELETE /v1/scheduled_tasks.

Returns: JSON {"ok": true}.

list_tasks tier 0–1

Return scheduled tasks visible to this group. Use for a plain task dump; prefer inspect_tasks when you also want task_run_logs or per-task history.

Source: ipc/ipc.go:2143 · Grant action: list_tasks (in tier1FixedActions). REST twin: GET /v1/scheduled_tasks.

Params: none. Returns: JSON array of core.Task.

pause_task tier 0–1

Mark a scheduled task paused so it stops firing but is preserved. Use when suspending a task temporarily.

Source: ipc/ipc.go:2111 · Grant action: pause_task (in tier1FixedActions) · auth.Authorize on task owner. REST twin: POST /v1/scheduled_tasks/pause.

Returns: JSON {"ok": true}.

resume_task tier 0–1

Re-activate a paused task so it resumes firing on its schedule. Use to undo pause_task. No effect on already-active or cancelled tasks.

Source: ipc/ipc.go:2114 · Grant action: resume_task (in tier1FixedActions). REST twin: POST /v1/scheduled_tasks/resume.

Returns: JSON {"ok": true}.

schedule_task tier 0–1

Create a scheduled prompt that fires against a target chat. cron accepts a 5-field cron expression, an integer millisecond interval, or an RFC3339 one-shot timestamp.

Source: ipc/ipc.go:2024 · Grant action: schedule_task (in tier1FixedActions) · Deduplicates against existing active tasks with same (folder, cron, prompt). REST twin: POST /v1/scheduled_tasks.

Returns: JSON {"taskId": "task-<ms>-<uuid8>"}.

routing

add_route tier 0–1

Append one routing rule. Preferred over set_routes for everything except full rewrites.

Source: ipc/ipc.go:1889 · Grant action: add_route (in tier1FixedActions) · auth.Authorize with RouteTarget. REST twin: POST /v1/routes.

Returns: JSON {"id": <routeId>}.

delete_route tier 0–1

Remove one routing rule by id. Use after list_routes/inspect_routing to surgically drop a rule. Cannot delete the caller's own default route (seq=0, target=own folder).

Source: ipc/ipc.go:1919 · Grant action: delete_route (in tier1FixedActions). REST twin: DELETE /v1/routes/{id}.

Returns: JSON {"deleted": true, "id": <id>}.

list_routes tier 0–1

Return the routing table rows this group can see. Use for a raw route dump; prefer inspect_routing when you also want JID→folder resolution or errored-chat context.

Source: ipc/ipc.go:1829 · Grant action: list_routes (in tier1FixedActions) · granted by default at tier 1. REST twin: GET /v1/routes.

Params: none. Returns: JSON {"routes": [...]}.

set_routes tier 0–1

Bulk-overwrite the full routing table for this folder subtree. Use only for wholesale reconfiguration; prefer add_route/delete_route for targeted edits.

Source: ipc/ipc.go:1837 · Grant action: set_routes (in tier1FixedActions) · Rejects targets outside the caller's folder subtree; refuses to drop the caller's seq=0 self-default. REST twin: PUT /v1/routes.

Returns: JSON {"updated": true, "count": <n>}.

egress

Manage the egress allowlist crackbox enforces. The proxy is default-deny — a folder only reaches hosts it (or an ancestor) has been allowed. Rules cascade down the tree: a rule at a parent folder opens the host for every descendant. All three gate on auth.AuthorizeStructural: tier 0 (root) is unrestricted; tier 1 is confined to its own folder and descendants; tier 2+ cannot manage egress. Backed by the network_rules table. Spec: 5/5 (egress_allowlist). Agent-only by design — there is no REST twin, and network_rules isn’t mounted at /v1/network_rules or listed in routd’s /openapi.json.

network_allow tier 0–1

Append an allowlist rule so folder and every descendant can reach host. Use when an agent needs a host the default-deny proxy blocks — a vendor API, say. host is a bare hostname (no scheme, no path), e.g. example.com. The rule cascades to all children.

Source: ipc/ipc.go:1950 · Grant action: network_allow · auth.AuthorizeStructural on folder; host validated by validHostname.

Returns: JSON {"allowed": true, "folder": "<f>", "host": "<host>"}.

network_deny tier 0–1

Remove an allowlist rule set on folder itself, closing access to host. Only drops a rule owned by this folder — a host inherited from an ancestor must be removed at that ancestor, not here.

Source: ipc/ipc.go:1976 · Grant action: network_deny · auth.AuthorizeStructural on folder.

Returns: JSON {"denied": true, "folder": "<f>", "host": "<host>"}.

network_list tier 0–1

Read the egress allowlist for folder. resolved is every host the folder can reach — its own rules, those inherited from ancestors, and the instance base. own is only the rules set on folder itself. Use to see why a host is reachable (own rule vs inherited) before adding or removing one.

Source: ipc/ipc.go:2001 · Grant action: network_list · auth.AuthorizeStructural on folder.

Returns: JSON {"folder": "<f>", "resolved": [...], "own": [...]}.

acl

list_acl tier 0–1

Audit the unified acl rows whose scope equals the target folder. Subsumes the pre-v0.38.0 get_grants/set_grants surface; writes now happen via arizuko grant or the dashd UI, not over MCP.

Source: ipc/ipc.go:2157 · Registration gated on id.Tier ≤ 1; bypasses the rule filter. Authorization: auth.AuthorizeStructural on the target folder.

Returns: JSON {"folder": "<f>", "acl": [{principal, action, scope, effect, params, predicate}, ...]}.

add_acl tier 0–1

Grant a principal access to a folder scope (writes an acl row). scope='**' confers the operator role. You can only grant within your own authority. Not for routes (add_route) or invites (invite_create). REST twin: POST /v1/acl.

Source: ipc/ipc.go:2353 · Grant action: add_acl · auth.AuthorizeStructural on scope.

Returns: JSON {"ok": true, "principal": "<p>", "scope": "<s>"}.

remove_acl tier 0–1

Revoke a principal's access to a folder scope (drops the acl row). scope='**' revokes the operator role. You can only revoke within your own authority. REST twin: DELETE /v1/acl.

Source: ipc/ipc.go:2382 · Grant action: remove_acl · auth.AuthorizeStructural on scope.

Returns: JSON {"ok": true, "principal": "<p>", "scope": "<s>"}.

invites

invite_create tier 0–1

Issue an invite token granting access to a path glob. The recipient accepts via /invite/<token> and gets an acl(admin, target_glob) row. The agent's authority must cover target_glob — you can't issue access you don't have.

Source: ipc/ipc.go:2187 · Grant action: invite_create · Issued by agent:<folder>.

Returns: JSON {token, target_glob, max_uses, expires_at?, accept_url?}.

invite_list tier 0–1

List the invite tokens this agent has issued — token, target glob, expiry, use count. Read-only; shows only this folder's invites. Use to audit outstanding invites before revoking. REST twin: GET /v1/invites.

Source: ipc/ipc.go:2296 · Grant action: invite_list · Scoped to issued_by="agent:<folder>"; no caller-supplied folder arg.

Params: none. Returns: JSON {"invites": [{token, target_glob, max_uses, used_count, expires_at?}, ...]}.

invite_revoke tier 0–1

Revoke an invite token you issued so it can no longer be redeemed. You may only revoke tokens issued by your own folder. Use invite_list to find your tokens. REST twin: DELETE /v1/invites/{token}.

Source: ipc/ipc.go:2323 · Grant action: invite_revoke · auth.AuthorizeStructural on caller's folder; ownership enforced in routd closure.

Returns: JSON {"ok": true, "token": "<t>"}.

web routes & web presence

Each group folder has a derived public hostname (<folder>.<HOSTING_DOMAIN>) that 302-redirects to its /pub/<folder>/ slot. No vhosts.json, no per-host config — the host is purely folder + "." + HOSTING_DOMAIN. An explicit WEB_VHOST_ALIASES entry overrides for the rare case where the folder label and the desired hostname differ. Use get_web_presence to discover the canonical host. The web_routes table (managed by set_web_route/del_web_route) is the inner layer: it controls access and redirects within /pub/<folder>/ after the vhost 302 lands.

del_web_route

Delete a web route by path. Only routes owned by this folder may be deleted (operators can delete any).

Source: ipc/ipc.go:2715 · Grant action: del_web_route.

Returns: text "ok", or error if not found / not owned.

get_web_presence tier 0–1

Report a folder's public web presence: derived canonical hostname, public/private base URLs, and the /pub/<folder>/ path that works even without HOSTING_DOMAIN. Read-only. Tier-1+ may only query own folder or descendants; tier-0 any. REST twin: GET /v1/web_presence?folder=<f>.

Source: ipc/ipc.go:2883 · Grant action: get_web_presence · Computed by ipc.WebPresenceFor from WEB_HOST, HOSTING_DOMAIN, WEB_VHOST_ALIASES.

Returns: JSON {hosting_domain, derived_host, alias_host?, canonical_host, public_base_url, private_base_url, pub_path}. pub_path is the vhost-independent canonical path.

list_web_routes

List all web routes owned by this folder.

Source: ipc/ipc.go:2743 · Grant action: list_web_routes.

Params: none. Returns: JSON array of {path_prefix, access, redirect_to, folder, created_at}.

set_web_route

Upsert a web route: control whether a URL path is public, auth-gated, denied, or redirected. Scoped to the caller's folder.

Source: ipc/ipc.go:2653 · Grant action: set_web_route.

Returns: text "ok".

identity

inspect_identity

Resolve a platform sender sub (e.g. tg:123, discord:abc) to its canonical identity and the full set of subs claimed by that identity. Advisory only — agents query, never enforce. Returns {identity:null, subs:[]} when the sub is unclaimed.

Source: ipc/inspect.go:98 · Registered only when db.GetIdentityForSub != nil; bypasses the grant-rule filter.

Returns: JSON {sub, identity, subs}.

system / JSON-RPC

submit_turn

Per-turn agent result delivery. Not a tool — a JSON-RPC method on the same MCP unix socket. Hidden from tools/list; the agent loop calls it directly with the turn payload. Idempotency enforced by routd on (folder, turn_id).

Source: ipc/ipc.go:407 (method dispatch) and ipc/ipc.go:419 (handler).

Returns: JSON-RPC {"result": {"ok": true}}, or a JSON-RPC error.

cost accounting

log_external_cost

Record one non-Anthropic LLM call against the folder's daily budget. Call this AFTER invoking an external model (e.g. codex exec --json for /oracle). Anthropic costs are captured automatically via submit_turn — this tool is for everything else the agent shells out to. Skipping it hides the call from cost-caps; the only operator-visible drift becomes the provider's own invoice. Spec 5/34. Registration is conditional on db.LogExternalCost being wired.

Source: ipc/ipc.go:848. Writes cost_log.

Returns: JSON {"ok": true, "cents": N}.

external REST tools

Beyond the hand-written MCP tools above, arizuko can expose a REST API as an MCP tool from a declarative [[ext]] TOML descriptor — no Go code per endpoint. A descriptor maps a tool name to one HTTP call; when the agent invokes it, routd makes the request directly on the host, injects the credential from the secrets table, and hands back only the response body. The token never enters the container. Loader: routd/ext.go; dispatcher: ipc/extcall.go CallExtTool.

the descriptor

Each provider is one [[ext]] block: a base URL, an [ext.auth] method that names the secret-store key to inject, and one [[ext.tool]] per endpoint. The tool's MCP name is <provider>_<tool> (e.g. cloudflare_dns_list). Path params in {braces} are filled from the call arguments; remaining args become the query string on GET/DELETE or the JSON body on POST/PUT/PATCH.

# connectors.toml (operator) or a built-in extproviders/*.toml
[[ext]]
name = "cloudflare"
base = "https://api.cloudflare.com/client/v4"

  [ext.auth]
  method = "bearer"
  secret = "CF_API_TOKEN"

  [[ext.tool]]
  name        = "dns_list"
  description = "List DNS records for a Cloudflare zone."
  scope       = "ext:cloudflare:dns:read"
  method      = "GET"
  path        = "/zones/{zone_id}/dns_records"

credential injection

The [ext.auth] method decides how the resolved secret reaches the upstream. Five shapes, all in CallExtTool:

The secret value is looked up per call for the triggering user (their own key overrides the folder default), never held in the descriptor, and scrubbed out of the response text before it returns to the agent.

built-in DNS providers

arizuko ships descriptors for four DNS registrars, ready to use once the operator sets the provider's token: Cloudflare (CF_API_TOKEN), Porkbun, Gandi, and Namecheap. Each covers the list/create/delete DNS operations. Operators add their own providers by dropping an [[ext]] block into connectors.toml in the instance dir.

grant gating

Every [[ext.tool]] carries a scope of the form ext:<service>:<operation> (e.g. ext:cloudflare:dns:write). Registration is grant-filtered like every other tool: the tool joins tools/list only when Authorize(folder, scope) passes, so an agent sees an external tool only where its folder is granted that scope. A call-time grant check stays as defense in depth.

notes & gotchas

• Registration is filtered by grants. registerRaw consults grants.MatchingRules(rules, name); if no rule matches the tool name, the tool is never added to tools/list. The matched rules are appended to the tool description as grants: [...] so the agent sees what it has been granted.
• Tier-gated registration on top of grants. refresh_groups (tier ≤ 2), set_work (tier ≤ 2), and list_acl (tier ≤ 1) wrap the AddTool call in a tier check — even at tier 0 with rules ["*"], tier-bracketing trumps glob match.
• Inline auth.Authorize past the grant filter. Most JID-targeted tools call authorizeJID after the grant check: a tier ≥ 1 caller cannot dispatch to a JID whose DefaultFolderForJID resolves outside the caller's folder subtree, even when grants would otherwise permit it.
• The secret broker is live. A connector or [[ext]] REST tool that needs a capability token has it resolved on the host at call time for the triggering user (their own key overrides the folder default), so the token never enters the container. Registration itself is per-call: registerRaw, granted, regSocial, raw srv.AddTool.
• Optional registration paths. Several tools are nil-guarded on the backing store function and silently absent if not wired: inspect_routing, inspect_tasks, inspect_session, inspect_identity, inspect_messages, find_messages (requires db.FindMessages), get_thread, fetch_history, all *_task tools (require db.GetTask).
• Cold-tier resources are a separate surface. Groups, acl, routes, web_routes, secrets, scheduled tasks and the like are not per-group MCP tools — they are CRUD resources driven by the resreg engine and reachable over REST, MCP, YAML manifests, and /openapi.json from one struct. The registry lives in routd. See OpenAPI.
• Route tools are granted at tier 1. tier1FixedActions lists list_routes, set_routes, add_route, delete_route — the names match the registered tools, so tier-1 callers get them by default. See grants/grants.go:160.