Add plan item
add_plan_itemAdds a user-visible item to the active plan when new work is discovered. When working in the current conversation, omit planId unless you already have the actual plan id; never pass a plan item id as planId. All new-item fields belong inside the nested item object, including item.position, item.parentItemId, and item.dependsOnItemIds. Never send position, label, or status at the top level. To insert a row, set item.position to the desired position. Include the exact field completionCriteria with model-visible completion criteria for the new item. Use this to append a new checklist/follow-up row; update_plan_item and update_plan_items cannot create a future position that does not already exist. Only add genuinely new executable work. Notes, evidence, limitations, fallbacks, or outcomes about work already represented by a plan item belong on that existing item. If the current attempt is partial or unsuccessful but the next action is still the same represented work, update the existing row instead of adding a child row. When adding work after a completed unsuccessful/partial item, the new item must reference that prior attempt with parentItemId or dependsOnItemIds so the audit chain is explicit. When more than one prior unsuccessful/partial attempt remains unresolved, use item.dependsOnItemIds with every unresolved attempt id; item.parentItemId is only enough for exactly one unresolved attempt. If add_plan_item returns unresolved attempt ids, retry once with item.dependsOnItemIds set to that exact id list, or use replace_plan_items once when you need to repair statuses and add the follow-up in one visible mutation. Do not add a waiting validation/start row for external work before the relevant domain tool has returned the real external id. First execute the active item with the relevant model-visible tools; then add or update the validation row with the returned externalKind/externalId evidence inside item.evidence (or patch.evidence for an update). A failed plan mutation changes no items. Adding an in_progress item records visible plan state only and does not perform domain work.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| planId | No | Optional plan UUID. In the current conversation, omit planId unless you already have the actual plan id from get_active_plan or a wake message. Never pass a plan item id here; target plan items through target.itemId or target.position. | |
| conversationId | No | Optional conversation UUID. Omit this field to use the current MCP conversation context; never pass placeholders such as `current`. |