Write Candor state
candor_writeCreate, update, or remove typed workspace state through validation and audited action history. Find an unfamiliar operation with candor_schema(query), then describe it with candor_schema(operation) for accepted_args, input_schema, confirmation requirements, and the correct tool. candor_preview provides read-only previews where supported; the operation contract defines any required prerequisites. A preview or reason does not grant approval. Put declared arguments in args and the request-body object in input. Includes open.acknowledge with args.checkpoint to mark a processed opening as seen. Returns an envelope with the changed object or receipt; inspect status, errors, and next_actions before assuming success. Invalid operations or arguments return schema recovery without executing the write. For an unknown outcome or an already-completed response that cannot be replayed, inspect workspace state before attempting another write.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments listed in accepted_args by candor_schema for the selected operation, including declared shorthand such as open.acknowledge checkpoint. Put action context such as parent_action at the top level, including when it comes from a returned next action. Request-body fields belong in input unless the operation explicitly accepts them as shorthand args. | |
| input | No | Inline request body matching the operation input schema returned by candor_schema. Put fields such as a note's about link inside this object. | |
| reason | No | Concise user-visible purpose recorded in immutable action history, including for financial reads. A reason is not approval. Root operations require it except fixed-reason orientation operations; continuations inherit the parent reason only when no reason is supplied. Fixed-reason orientation operations always use their system reason. | |
| task_key | No | Optional stable label grouping operations for the same user task. Omit to inherit the parent task key, if any. It does not schedule work or provide idempotency. | |
| operation | Yes | Exact operation id from candor_schema, such as notes.create. Use the tool indicated by its calls.mcp or next_call. | |
| parent_action | No | Existing action id in this workspace, typically returned in next_actions, whose root identity this continuation inherits. An omitted reason inherits the parent reason; an explicit reason is preserved, except for fixed-reason orientation operations. Omit for a new root action. | |
| idempotency_key | No | Stable opaque identity for one logical POST. Reuse only with the same method, path, actor, and body for transport retries. A completed receipt replays its original result, including a refusal; changed input with the same key is rejected. After a refused action and access recovery, use a new key for the new attempt. Follow retryable and recovery guidance if the operation is still running or its outcome is unknown. If omitted, MCP derives a key from this request identity; use an explicit key to deduplicate separate tool invocations. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| action | No | ||
| errors | Yes | ||
| status | Yes | ||
| metadata | No | ||
| warnings | Yes | ||
| request_id | Yes | ||
| generated_at | Yes | ||
| next_actions | Yes | ||
| user_message | No | ||
| data_freshness | No | ||
| schema_version | Yes |