Write Candor state
candor_writeCreates, updates, or removes typed state in the user's private Candor workspace, such as budgets, goals, categorization rules, notes, and confirmed recurring payments, through validated Candor API operations (API reference: https://candor.money/developers). Use to keep what the conversation settles as it settles, without waiting to be asked: a goal the person describes with the measure that tracks it, a budget, a note of what they said, a rule for what transactions mean; and to send product feedback, which the feedback.submit operation delivers to the Candor team. Declared arguments go in args and the request body goes in input. Saving what you work out with the person (budgets, goals, rules, corrections, notes) needs no separate confirmation from them. An operation that does need one states it in its contract; a recorded reason or a preview is not a confirmation. Some operations have other prerequisites stated in their contract. The open.acknowledge operation marks a processed opening as seen. Returns the changed object or a receipt with status, errors, and next_actions; an invalid operation or argument returns a schema error without writing. Every write is recorded with its reason in the workspace's action history. It cannot move money or change anything at a financial institution.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | The selected operation's accepted_args, as published in its contract, including declared shorthand such as the open.acknowledge checkpoint. Action context such as parent_action is a top-level field, not an argument. Request-body fields belong in input unless the operation accepts them as shorthand args. | |
| input | No | Inline request body matching the operation's published input schema. Fields such as a note's about link belong inside this object. | |
| reason | No | Concise user-visible purpose recorded in immutable action history, including for financial reads. It names the task, such as "Check this month's dining budget", and needs no personal details from the conversation. 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 the Candor operation catalog, such as notes.create. | |
| parent_action | No | Existing action id in this workspace, typically returned in next_actions, that this continuation follows. A continuation with the parent's reason joins the parent's root action, whether the reason is omitted (it is then inherited) or repeated exactly; a distinct explicit reason is preserved and starts a new root that keeps this parent link. Fixed-reason orientation operations always start a new root. 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 |