prompts
prompts.blocks_get
Get Prompt Block Overrides
Effects: read
Read the stored prompt-block overrides. Without agent_id: the workspace level (applies to every agent). With agent_id: that agent's own layer (beats the workspace per field) plus its legacy include_* toggles. Missing keys and null fields mean 'inherit'.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Agent id for the agent level; omit for the workspace level. |
prompts.blocks_preview
Preview Assembled Prompt
Effects: read
Assemble an agent's system prompt through the REAL builder and return it block by block with attribution (id, kind, cache phase, token estimate), the cached-prefix/dynamic-suffix split, and any ignored stale overrides or missing translations. Byte-equality with the production assembly is verified — the preview cannot lie. Use after prompts.blocks_update to see the effect.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | yes | Agent whose prompt to assemble. |
thread_id | integer | no | Optional thread to load real situation/history context from. |
prompts.blocks_registry
Prompt Blocks Registry
Effects: read
List every block the platform assembles into agent system prompts: id, kind (fact = platform data, guidance = platform text you can rewrite or disable, user = your own text), cache phase, order, the fact labels you can reference from your instructions (e.g. thread_id in [SITUATION]), which labels are locked by enabled tools, and each guidance text's platform default with its md5. Read this before prompts.blocks_update.
Arguments
No arguments.
prompts.blocks_update
Update Prompt Block Overrides
Effects: write
Replace the stored prompt-block overrides at one level (workspace when agent_id is omitted, else that agent). prompt_blocks is the FULL desired object for the level: {"<block_id>": {"enabled": bool|null, "text": str|null (guidance blocks only), "order": int|null (reorders within the block's cache tier), "hidden_rows": [label, ...] (fact blocks only)}}. Pass null for an entry to remove it (inherit). Fails loudly: unknown block/label ids, editing a fact block's text, empty text, size caps, and newly hiding a fact row that an enabled tool consumes are all rejected with the full error list — read prompts.blocks_registry for valid ids. Pre-existing stored state is never re-validated (grandfathered).
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Agent id for the agent level; omit for the workspace level. |
prompt_blocks | object | yes | Full desired overrides object for the level (see tool description for the entry shape). |
prompts.get
Get Prompt Template
Effects: read
Get full content of a prompt template: system instructions (prompt_text) and auto-reply rules.
Run prompts.list first to find the prompt_id.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
prompt_id | integer | yes | ID of the prompt template to fetch |
prompts.list
List Prompt Templates
Effects: read
List all prompt templates in this workspace.
Returns id + name + description + category so you know which prompt_id to use in prompts.get or prompts.update.
Arguments
No arguments.
prompts.prompt_history
Prompt Template History
Effects: read
List past versions of a prompt template's prompt_text. Every edit is snapshotted to an append-only table — use this to browse history and find a version_number for prompts.prompt_restore.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
before_version | integer | no | Cursor: return versions strictly below this version_number (min 1.0) |
limit | integer | no | Max versions to return (1-200, default 50) (default 50; min 1.0; max 200.0) |
prompt_id | integer | yes | ID of the prompt template |
prompts.prompt_restore
Restore Prompt Template
Effects: write
Restore a past version of a prompt template by version_number. Creates a new version pointing at the restored content — history is preserved. Fans out to every agent using this template without a per-agent override; the response includes affected_agents as a receipt of the fan-out.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
prompt_id | integer | yes | ID of the prompt template |
reason | string | no | Optional: why this restore is happening (shows up in history UI) |
version_number | integer | yes | The version_number to restore (get it from prompts.prompt_history) (min 1.0) |
prompts.update
Update Prompt Template
Effects: write
Update a prompt template's name, system instructions, or auto-reply rules.
Changes affect every agent using this template, unless the agent has its own override (set via agents.update → prompt_text).
All parameters except prompt_id are optional — only provided fields are updated.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
auto_reply_rules | string | no | Pre-classifier rules that run BEFORE the main AI. Format: bullet list of conditions → actions (SKIP / SIMPLE_REPLY / SEARCH / CALENDAR). Pass null to clear. |
description | string | no | New description for the prompt template |
name | string | no | New name for the prompt template |
prompt_id | integer | yes | ID of the prompt template to update |
prompt_text | string | no | The AI system prompt: persona, tone, rules, behavior. |