AgentPlaybooks MCP · AgentPlaybooks

{
  "name": "list_playbooks",
  "description": "List playbooks owned by or shared with the authenticated user, including access role and content counts. Read-only; it does not create or modify playbooks. Use get_playbook when you need the singleton persona, skills, connected servers, and memory for one playbook. Requires playbooks:read or full permission.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "playbooks": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "guid": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "current_user_role": {
              "type": "string"
            },
            "persona_count": {
              "type": "number"
            }
          },
          "additionalProperties": true
        }
      }
    },
    "required": [
      "playbooks"
    ]
  }
}

{
  "name": "create_playbook",
  "description": "Create a new playbook container for a singleton persona, skills, and memory. Each call inserts a new playbook; it does not upsert by name. Requires playbooks:write or full permission. Use update_playbook to change an existing playbook, not this tool.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Name of the playbook"
      },
      "description": {
        "type": "string",
        "description": "Description of what the playbook is for"
      },
      "visibility": {
        "type": "string",
        "enum": [
          "public",
          "private",
          "unlisted"
        ],
        "description": "Visibility of the playbook",
        "default": "private"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Discovery and organization tags"
      },
      "persona_name": {
        "type": "string",
        "description": "Initial persona name"
      },
      "persona_system_prompt": {
        "type": "string",
        "description": "Initial persona/system prompt"
      },
      "persona_metadata": {
        "type": "object",
        "description": "Initial persona metadata"
      },
      "instructions": {
        "type": "string",
        "description": "Always-on project instructions (the AGENTS.md / CLAUDE.md content). Separate from the persona: the persona is who the agent is, these are the rules of this project."
      }
    },
    "required": [
      "name"
    ]
  }
}

{
  "name": "get_playbook",
  "description": "Get a playbook with its singleton persona, skills, connected MCP servers, and memory. This is the only persona retrieval tool; there is no get_persona. Read-only. Requires playbooks:read or full permission. Use list_playbooks to discover IDs first, and get_skill when you need one skill's full content rather than the playbook summary.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID of the playbook"
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "delete_playbook",
  "description": "Permanently delete a playbook and all of its contents (persona, skills, memory, API keys, canvas, and secrets). This cannot be undone. Requires playbooks:write or full permission, and only the owner may delete. Do not use this to reset a persona (delete_persona) or remove a single skill or memory; those have dedicated tools.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID of the playbook to delete"
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "create_persona",
  "description": "Set the playbook's singleton persona name and system prompt. This does not add a second persona; it is a backward-compatible alias that overwrites those fields. Requires personas:write or full permission. Prefer update_persona to change a subset of fields. Use update_playbook only when you also need playbook name, visibility, config, or project instructions. Do not use delete_persona unless you intend to reset to the default Assistant.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID of the playbook"
      },
      "name": {
        "type": "string",
        "description": "Name of the persona"
      },
      "system_prompt": {
        "type": "string",
        "description": "The system prompt that defines this persona's behavior"
      },
      "metadata": {
        "type": "object",
        "description": "Optional metadata"
      }
    },
    "required": [
      "playbook_id",
      "name",
      "system_prompt"
    ]
  }
}

{
  "name": "update_persona",
  "description": "Update the singleton persona's name, system prompt, or metadata without resetting to defaults. persona_id must equal playbook_id because the persona is stored on the playbook row. Requires personas:write or full permission. Use create_persona to replace name and system prompt together, delete_persona to reset to the default Assistant, and update_playbook when changing playbook-level fields as well.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID of the playbook"
      },
      "persona_id": {
        "type": "string",
        "description": "Must equal playbook_id; the persona is a singleton stored on the playbook"
      },
      "name": {
        "type": "string",
        "description": "New name"
      },
      "system_prompt": {
        "type": "string",
        "description": "New system prompt"
      },
      "metadata": {
        "type": "object",
        "description": "New metadata"
      }
    },
    "required": [
      "playbook_id",
      "persona_id"
    ]
  }
}

{
  "name": "delete_persona",
  "description": "Reset the playbook's singleton persona to the default Assistant name and system prompt. Despite the delete_* name, this is not a hard delete: each playbook always keeps exactly one logical persona, so the fields are overwritten rather than removed. persona_id must equal playbook_id because the persona is stored on the playbook row. Custom name, system prompt, and metadata are permanently replaced and cannot be undone. Requires personas:write or full permission. Use update_persona to change fields without resetting, create_persona to set a new identity, and delete_playbook only when the entire playbook should be removed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID of the playbook"
      },
      "persona_id": {
        "type": "string",
        "description": "Must equal playbook_id; the persona is a singleton stored on the playbook"
      }
    },
    "required": [
      "playbook_id",
      "persona_id"
    ]
  }
}

{
  "name": "find_tools",
  "description": "Search this playbook's complete tool catalog by keyword: the built-in playbook tools (memory, skills, canvas, workflow runs, secrets) and every connected server's federated tools (names like supabase__execute_sql or cloudflare__search). Matches against tool names and descriptions; a name match ranks above a description match. Returns up to `limit` (default 10, max 25) entries with name, description, and full input schema. Every returned tool can be called directly by name even when it is absent from tools/list — the advertised list is a view, not a boundary, unless this connection was pinned with ?toolset=. Read-only and free of side effects. Use this when the tool you need is not in your current list, before concluding a capability is missing. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "query": {
        "type": "string",
        "description": "Keywords to match against tool names and descriptions, e.g. 'sql tables' or 'archive memory'"
      },
      "limit": {
        "type": "number",
        "description": "Maximum matches to return (default 10, max 25)"
      }
    },
    "required": [
      "playbook_id",
      "query"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "matches": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Callable tool name"
            },
            "description": {
              "type": "string"
            },
            "inputSchema": {
              "type": "object"
            }
          },
          "required": [
            "name",
            "description",
            "inputSchema"
          ]
        }
      }
    },
    "required": [
      "matches"
    ]
  }
}

{
  "name": "list_skills",
  "description": "List every skill currently attached to this playbook, returning id, name, description, content, licence, and priority ordered by priority descending. Read-only; it does not create or change skills. Use this to discover skill_id values before get_skill, update_skill, or delete_skill. Do not use list_skill_versions, which lists historical revisions of a single skill, or get_playbook, which only summarizes skills. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      }
    },
    "required": [
      "playbook_id"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "skills": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Skill UUID"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "content": {
              "type": [
                "string",
                "null"
              ]
            },
            "licence": {
              "type": [
                "string",
                "null"
              ]
            },
            "publisher_id": {
              "type": [
                "string",
                "null"
              ]
            },
            "priority": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        }
      }
    },
    "required": [
      "skills"
    ]
  }
}

{
  "name": "get_skill",
  "description": "Return the full definition of one skill in this playbook, including name, description, content, priority, and attachments. Identify the skill with skill_id, which may be a UUID or the skill's kebab-case name. This lookup does not modify the skill. Use list_skills first to discover IDs and names. Do not use list_skill_versions (historical revisions) or get_playbook (persona and summaries, not full skill content). Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "skill_id": {
        "type": "string",
        "description": "Skill ID or name"
      }
    },
    "required": [
      "playbook_id",
      "skill_id"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "playbook_id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "description": {
        "type": [
          "string",
          "null"
        ]
      },
      "content": {
        "type": [
          "string",
          "null"
        ]
      },
      "licence": {
        "type": [
          "string",
          "null"
        ]
      },
      "publisher_id": {
        "type": [
          "string",
          "null"
        ]
      },
      "priority": {
        "type": [
          "number",
          "null"
        ]
      },
      "created_at": {
        "type": "string"
      },
      "skill_attachments": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  }
}

{
  "name": "read_memory",
  "description": "Read one memory entry by key and return its value, tags, tier, summary, and metadata. This is not a pure read: it increments access_count and updates last_accessed_at as a side effect, without changing the stored value. There is no update_memory; use write_memory to overwrite a key. Use search_memory to find keys, get_memory_context for a tiered summary, or get_memory_tree for hierarchical task graphs. Do not pass memory_type; that filter belongs to search_memory. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "key": {
        "type": "string",
        "description": "Memory key to read"
      }
    },
    "required": [
      "playbook_id",
      "key"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string"
      },
      "value": {},
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "description": {
        "type": [
          "string",
          "null"
        ]
      },
      "tier": {
        "type": "string",
        "enum": [
          "working",
          "contextual",
          "longterm"
        ]
      },
      "priority": {
        "type": "number"
      },
      "parent_key": {
        "type": [
          "string",
          "null"
        ]
      },
      "summary": {
        "type": [
          "string",
          "null"
        ]
      },
      "access_count": {
        "type": "number"
      },
      "updated_at": {
        "type": "string"
      },
      "memory_at": {
        "type": "string",
        "format": "date-time"
      },
      "is_archived": {
        "type": "boolean"
      }
    }
  }
}

{
  "name": "search_memory",
  "description": "Search memory keys, JSON values, descriptions and summaries. Defaults to current, non-archived memories. scope='archived' searches archived entries and previous versions; scope='all' searches both. Results include memory_at and history_id (null for current entries). Use get_memory_history for one key's previous versions, or read_memory for its current value. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "search": {
        "type": "string",
        "description": "Literal text in keys, JSON values, descriptions and summaries"
      },
      "scope": {
        "type": "string",
        "enum": [
          "active",
          "archived",
          "all"
        ],
        "default": "active"
      },
      "after": {
        "type": "string",
        "format": "date-time",
        "description": "Inclusive lower bound on memory_at"
      },
      "before": {
        "type": "string",
        "format": "date-time",
        "description": "Inclusive upper bound on memory_at"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 100
      },
      "offset": {
        "type": "integer",
        "minimum": 0,
        "default": 0
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Filter by tags (any match)"
      },
      "tier": {
        "type": "string",
        "enum": [
          "working",
          "contextual",
          "longterm"
        ],
        "description": "Filter by memory tier"
      },
      "memory_type": {
        "type": "string",
        "enum": [
          "flat",
          "hierarchical"
        ],
        "description": "Filter by memory type"
      },
      "status": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "completed",
          "failed",
          "blocked"
        ],
        "description": "Filter by task status (hierarchical only)"
      },
      "include_children": {
        "type": "boolean",
        "description": "Include child memories in results",
        "default": false
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "get_memory_history",
  "description": "Read previous versions of a memory by its current key, including original memory_at and saved contents. History is excluded from normal search. To restore a version, write its contents and memory_at with write_memory and is_archived=false. Read-only. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "key": {
        "type": "string"
      },
      "search": {
        "type": "string",
        "description": "Optional text within this memory's history"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "default": 100
      },
      "offset": {
        "type": "integer",
        "minimum": 0,
        "default": 0
      }
    },
    "required": [
      "playbook_id",
      "key"
    ]
  }
}

{
  "name": "write_memory",
  "description": "Create or update a memory by key; previous contents are saved automatically and readable with get_memory_history. memory_at is optional and defaults to this save's time; supply an ISO timestamp to preserve an earlier time. is_archived=true hides the entry from normal search/context; false restores it. Tier controls context priority independently of archiving. Requires memory:write or full permission. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "key": {
        "type": "string",
        "description": "Memory key"
      },
      "value": {
        "description": "JSON value to store"
      },
      "memory_at": {
        "type": "string",
        "format": "date-time",
        "description": "Memory time including timezone; defaults to save time"
      },
      "is_archived": {
        "type": "boolean",
        "description": "Hide from normal search; false restores an archived entry"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Tags for categorization"
      },
      "description": {
        "type": "string",
        "description": "Human-readable description"
      },
      "tier": {
        "type": "string",
        "enum": [
          "working",
          "contextual",
          "longterm"
        ],
        "description": "Memory tier (default: contextual)"
      },
      "priority": {
        "type": "number",
        "description": "Priority 1-100 (default: 50)"
      },
      "parent_key": {
        "type": "string",
        "description": "Parent memory key for hierarchical organization"
      },
      "summary": {
        "type": "string",
        "description": "Compact summary for context views"
      },
      "memory_type": {
        "type": "string",
        "enum": [
          "flat",
          "hierarchical"
        ],
        "description": "flat (default) or hierarchical for task graphs"
      },
      "status": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "completed",
          "failed",
          "blocked"
        ],
        "description": "Task status (for hierarchical task tracking)"
      },
      "metadata": {
        "type": "object",
        "description": "Graph metadata: dependencies, thread assignment, progress, etc."
      }
    },
    "required": [
      "playbook_id",
      "key",
      "value"
    ]
  }
}

{
  "name": "delete_memory",
  "description": "Permanently delete a memory and its saved history. Requires memory:write or full permission. To hide an entry while retaining its content, use archive_memories instead. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "key": {
        "type": "string",
        "description": "Memory key to delete"
      }
    },
    "required": [
      "playbook_id",
      "key"
    ]
  }
}

{
  "name": "consolidate_memories",
  "description": "Consolidate related memories under a new parent memory with a summary. Child rows stay readable; by default they are archived to the longterm tier rather than deleted. Requires memory:write or full permission. Use delete_memory only when a key should be destroyed, and archive_memories to move entries to longterm without creating a parent. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "memory_keys": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Keys of memories to consolidate"
      },
      "parent_key": {
        "type": "string",
        "description": "New parent memory key"
      },
      "summary": {
        "type": "string",
        "description": "Summary of consolidated memories"
      },
      "parent_tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Tags for parent memory"
      },
      "archive_children": {
        "type": "boolean",
        "description": "Move children to longterm tier",
        "default": true
      }
    },
    "required": [
      "playbook_id",
      "memory_keys",
      "parent_key",
      "summary"
    ]
  }
}

{
  "name": "promote_memory",
  "description": "Restore a memory's visibility, promote it to a higher tier or boost its priority for active use. This tool cannot demote; use archive_memories to archive entries. Repeating the call with priority_boost increases priority again. Requires memory:write or full permission. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "key": {
        "type": "string",
        "description": "Memory key to promote"
      },
      "target_tier": {
        "type": "string",
        "enum": [
          "working",
          "contextual"
        ],
        "description": "Target tier (cannot demote with this tool)"
      },
      "priority_boost": {
        "type": "number",
        "description": "Amount to increase priority (0-50)",
        "default": 10
      }
    },
    "required": [
      "playbook_id",
      "key"
    ]
  }
}

{
  "name": "get_memory_context",
  "description": "Get a context-optimized view of memories: full working memory, summaries for contextual, and keys only for longterm. Read-only. Use this to pack a prompt; use read_memory for one key, search_memory to filter, and get_memory_tree for parent-child task graphs. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "include_tiers": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "working",
            "contextual",
            "longterm"
          ]
        },
        "description": "Tiers to include (default: working, contextual)"
      },
      "max_items": {
        "type": "number",
        "description": "Maximum items per tier",
        "default": 20
      },
      "expand_keys": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Keys to show full content regardless of tier"
      },
      "tags_filter": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Only include memories with these tags"
      }
    },
    "required": [
      "playbook_id"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "tiers": {
        "type": "object",
        "additionalProperties": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      },
      "total_items": {
        "type": "number"
      }
    },
    "required": [
      "tiers",
      "total_items"
    ]
  }
}

{
  "name": "archive_memories",
  "description": "Hide matching memories from normal search and context, retaining them in the longterm tier. Search scope='archived' to find them or read_memory by key. Filters combine as AND; older_than_hours uses memory_at. Permanent-retention entries are skipped. promote_memory restores visibility. Requires memory:write or full permission. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "keys": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Specific keys to archive"
      },
      "older_than_hours": {
        "type": "number",
        "description": "Archive memories older than X hours"
      },
      "from_tier": {
        "type": "string",
        "enum": [
          "working",
          "contextual",
          "longterm"
        ],
        "description": "Only archive from this tier"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Only archive memories with these tags"
      },
      "generate_summaries": {
        "type": "boolean",
        "description": "Auto-generate summaries if missing",
        "default": false
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "get_memory_tree",
  "description": "Get a hierarchical tree of memories showing parent-child relationships and per-node status. Read-only. Use this to visualize task graphs; use search_memory to filter flat lists, get_memory_context for a tiered prompt view, and read_memory for a single key's full value. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "root_key": {
        "type": "string",
        "description": "Start from this key (omit for all roots)"
      },
      "max_depth": {
        "type": "number",
        "description": "Maximum tree depth",
        "default": 3
      },
      "include_values": {
        "type": "boolean",
        "description": "Include full values (false = summaries only)",
        "default": false
      }
    },
    "required": [
      "playbook_id"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "root": {
        "type": [
          "string",
          "null"
        ]
      },
      "tree": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "total_nodes": {
        "type": "number"
      }
    },
    "required": [
      "root",
      "tree",
      "total_nodes"
    ]
  }
}

{
  "name": "create_task_graph",
  "description": "Create a hierarchical task plan in one call: a parent plan memory plus a child node per subtask. Upserts by key, so repeating the same plan_key overwrites the previous graph. Requires memory:write or full permission. Use write_memory for a single node, update_task_status to move a node through pending/running/completed, and get_memory_tree to inspect the graph. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "plan_key": {
        "type": "string",
        "description": "Key for the root plan memory"
      },
      "plan_summary": {
        "type": "string",
        "description": "High-level summary of the entire plan"
      },
      "tasks": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "description": "Task key (will be prefixed with plan_key/)"
            },
            "description": {
              "type": "string",
              "description": "What this task does"
            },
            "value": {
              "type": "object",
              "description": "Task data (instructions, params, etc.)"
            },
            "depends_on": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Keys of tasks this depends on"
            },
            "tags": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Task tags"
            }
          },
          "required": [
            "key",
            "description"
          ]
        },
        "description": "List of subtasks to create"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Tags for the plan"
      }
    },
    "required": [
      "playbook_id",
      "plan_key",
      "plan_summary",
      "tasks"
    ]
  }
}

{
  "name": "update_task_status",
  "description": "Update the status of a task node in a hierarchical plan. When all children of a parent are completed, the parent is auto-updated. Returns the current subtree state. Requires memory:write or full permission. Use create_task_graph to build the plan, not this tool. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "key": {
        "type": "string",
        "description": "Task memory key to update"
      },
      "status": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "completed",
          "failed",
          "blocked"
        ],
        "description": "New status"
      },
      "result": {
        "type": "object",
        "description": "Task result data to store in value"
      },
      "summary": {
        "type": "string",
        "description": "Updated summary with results"
      }
    },
    "required": [
      "playbook_id",
      "key",
      "status"
    ]
  }
}

{
  "name": "list_canvas",
  "description": "List canvas documents in a workflow run. Canvas documents are collaborative markdown files that multiple agents can edit in parallel. Omit run_id to list documents across all runs. Read-only. Use read_canvas for content and get_canvas_toc for section IDs. There is no get_run; list_runs returns run records. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID. Omit to list documents across all runs."
      }
    },
    "required": [
      "playbook_id"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "documents": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "run_id": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "sort_order": {
              "type": "number"
            },
            "version": {
              "type": "number"
            },
            "updated_at": {
              "type": "string"
            },
            "metadata": {
              "type": "object"
            }
          }
        }
      }
    },
    "required": [
      "documents"
    ]
  }
}

{
  "name": "read_canvas",
  "description": "Read a canvas document. Returns full content, sections structure, and metadata. Optionally read a specific section by ID. Read-only. Use get_canvas_toc to discover section IDs before patch_canvas_section, and list_canvas to find slugs. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "slug": {
        "type": "string",
        "description": "Document slug"
      },
      "section_id": {
        "type": "string",
        "description": "Optional: read only this section"
      }
    },
    "required": [
      "playbook_id",
      "run_id",
      "slug"
    ]
  }
}

{
  "name": "write_canvas",
  "description": "Create or fully replace a canvas document. Markdown headings are auto-parsed into sections for parallel editing. A replace overwrites prior content and cannot be undone. Requires canvas:write or full permission. Use patch_canvas_section for partial updates and lock_canvas_section before multi-agent edits. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "slug": {
        "type": "string",
        "description": "URL-friendly document identifier"
      },
      "name": {
        "type": "string",
        "description": "Document title"
      },
      "content": {
        "type": "string",
        "description": "Full markdown content"
      },
      "metadata": {
        "type": "object",
        "description": "Custom document metadata"
      }
    },
    "required": [
      "playbook_id",
      "run_id",
      "slug",
      "name",
      "content"
    ]
  }
}

{
  "name": "patch_canvas_section",
  "description": "Edit a specific section of a canvas document. Parallel-safe: only the targeted section is updated. Requires canvas:write or full permission. Lock the section first in multi-agent scenarios. Use write_canvas only when replacing the whole document, and get_canvas_toc to obtain section_id. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "slug": {
        "type": "string",
        "description": "Document slug"
      },
      "section_id": {
        "type": "string",
        "description": "Section ID from get_canvas_toc"
      },
      "content": {
        "type": "string",
        "description": "New section content (markdown)"
      },
      "heading": {
        "type": "string",
        "description": "Optional: new heading text"
      }
    },
    "required": [
      "playbook_id",
      "run_id",
      "slug",
      "section_id",
      "content"
    ]
  }
}

{
  "name": "get_canvas_toc",
  "description": "Get the table of contents for a canvas document. Returns section IDs, headings, and levels for navigation and patch_canvas_section. Read-only. Use read_canvas for full markdown and list_canvas to discover slugs. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "slug": {
        "type": "string",
        "description": "Document slug"
      }
    },
    "required": [
      "playbook_id",
      "run_id",
      "slug"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "slug": {
        "type": "string"
      },
      "toc": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "heading": {
              "type": "string"
            },
            "level": {
              "type": "number"
            },
            "locked_by": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      }
    },
    "required": [
      "name",
      "slug",
      "toc"
    ]
  }
}

{
  "name": "lock_canvas_section",
  "description": "Lock a section for exclusive editing so other agents cannot modify it. Requires canvas:write or full permission. Always unlock_canvas_section when finished. Do not use this to edit content; pair it with patch_canvas_section. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "slug": {
        "type": "string",
        "description": "Document slug"
      },
      "section_id": {
        "type": "string",
        "description": "Section ID to lock"
      },
      "locked_by": {
        "type": "string",
        "description": "Agent identifier"
      }
    },
    "required": [
      "playbook_id",
      "run_id",
      "slug",
      "section_id",
      "locked_by"
    ]
  }
}

{
  "name": "unlock_canvas_section",
  "description": "Unlock a previously locked canvas section so other agents can edit it. Requires canvas:write or full permission. Use lock_canvas_section to take the lock; this tool does not change section content. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "slug": {
        "type": "string",
        "description": "Document slug"
      },
      "section_id": {
        "type": "string",
        "description": "Section ID to unlock"
      }
    },
    "required": [
      "playbook_id",
      "run_id",
      "slug",
      "section_id"
    ]
  }
}

{
  "name": "create_skill",
  "description": "Create a new skill for this playbook. Use this to expand capabilities. Requires full or skills:write permission. Use update_skill to change an existing skill and list_skills to check for name collisions first. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "Agent Skills-compatible name (lowercase kebab-case, e.g. data-analyzer)"
      },
      "description": {
        "type": "string",
        "description": "What the skill does and when the agent should use it"
      },
      "content": {
        "type": "string",
        "description": "The instructions/prompt/code for the skill"
      },
      "priority": {
        "type": "number",
        "description": "Priority level (default 50)"
      }
    },
    "required": [
      "playbook_id",
      "name",
      "content"
    ]
  }
}

{
  "name": "update_skill",
  "description": "Update an existing skill in this playbook. Requires full or skills:write permission. Use create_skill to add a skill, list_skill_versions before a risky edit, and rollback_skill to restore a previous version. Do not use this to delete a skill. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "skill_id": {
        "type": "string",
        "description": "ID or name of the skill to update"
      },
      "name": {
        "type": "string",
        "description": "New name"
      },
      "description": {
        "type": "string",
        "description": "New description"
      },
      "content": {
        "type": "string",
        "description": "New content/instructions"
      },
      "priority": {
        "type": "number",
        "description": "New priority level"
      }
    },
    "required": [
      "playbook_id",
      "skill_id"
    ]
  }
}

{
  "name": "delete_skill",
  "description": "Permanently delete a skill from this playbook. This cannot be undone except by recreating the skill. Requires full or skills:write permission. Use rollback_skill to restore a previous version instead of deleting, and update_skill to change content in place. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "skill_id": {
        "type": "string",
        "description": "ID or name of the skill to delete"
      }
    },
    "required": [
      "playbook_id",
      "skill_id"
    ]
  }
}

{
  "name": "list_skill_versions",
  "description": "List historical versions of a skill for auditing or rollback. Read-only. Use this before rollback_skill; use get_skill for the current definition and list_skills for every skill in the playbook. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "skill_id": {
        "type": "string",
        "description": "ID or name of the skill"
      },
      "limit": {
        "type": "number",
        "description": "Max versions to return (default 10)"
      }
    },
    "required": [
      "playbook_id",
      "skill_id"
    ]
  }
}

{
  "name": "rollback_skill",
  "description": "Rollback a skill to a previous version recorded by list_skill_versions. The current definition is replaced and cannot be recovered except by rolling forward to another stored version. Requires full or skills:write permission. Do not use delete_skill when you only need to revert. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "version_id": {
        "type": "string",
        "description": "The specific version ID from list_skill_versions to rollback to"
      }
    },
    "required": [
      "playbook_id",
      "version_id"
    ]
  }
}

{
  "name": "update_playbook",
  "description": "Update this playbook's name, description, visibility, tags, config, singleton persona fields, or always-on project instructions. Replacement fields overwrite previous values. Handle with extreme care. Requires full or playbooks:write permission. Changing persona_system_prompt here overlaps with update_persona and create_persona; use those when only the persona should change. There is no separate get_persona: read the persona via get_playbook. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "New playbook name"
      },
      "description": {
        "type": "string",
        "description": "New playbook description"
      },
      "visibility": {
        "type": "string",
        "enum": [
          "public",
          "private",
          "unlisted"
        ],
        "description": "New visibility"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Replacement discovery tags"
      },
      "config": {
        "type": "object",
        "description": "Replacement playbook configuration"
      },
      "persona_name": {
        "type": "string",
        "description": "New persona name"
      },
      "persona_system_prompt": {
        "type": "string",
        "description": "New core system instructions"
      },
      "persona_metadata": {
        "type": "object",
        "description": "New metadata JSON"
      },
      "instructions": {
        "type": "string",
        "description": "New always-on project instructions (the AGENTS.md / CLAUDE.md content). Kept separate from the persona: the persona is who the agent is, these are the rules of this project."
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "list_mcp_servers",
  "description": "List the MCP and OpenAPI servers connected to this playbook, including transport metadata and discovered capability counts. Read-only. There is no get_mcp_server; this list is the detail view. Do not use this to invoke a connected tool—use call_connected_tool. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "call_connected_tool",
  "description": "Call a tool on one of this playbook's connected MCP or OpenAPI servers. Arguments are forwarded as-is and the result mirrors the connected tool, including any side effects that tool has in the outside world. Requires tools:call or full permission. Use list_mcp_servers to discover server_id and tool_name. Do not use this to manage connection records; use create_mcp_server, update_mcp_server, or delete_mcp_server. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "server_id": {
        "type": "string",
        "description": "Connected server UUID or name"
      },
      "tool_name": {
        "type": "string",
        "description": "Tool name exposed by the connected server"
      },
      "arguments": {
        "type": "object",
        "description": "Arguments passed to the connected tool"
      }
    },
    "required": [
      "playbook_id",
      "server_id",
      "tool_name"
    ]
  }
}

{
  "name": "create_mcp_server",
  "description": "Connect an MCP or OpenAPI server to this playbook by storing its transport configuration. This writes playbook state; it does not by itself invoke remote tools. Requires playbooks:write or full permission. Use call_connected_tool to invoke a discovered tool, and list_mcp_servers to inspect connections. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "Display name of the connected server"
      },
      "description": {
        "type": "string",
        "description": "What this server provides"
      },
      "tools": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Known tool definitions, if already discovered"
      },
      "resources": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Known resource definitions, if already discovered"
      },
      "transport_type": {
        "type": "string",
        "enum": [
          "stdio",
          "http",
          "sse",
          "openapi"
        ],
        "description": "Connection type (default: http)"
      },
      "transport_config": {
        "type": "object",
        "description": "Transport-specific configuration. Do not put plaintext secrets here."
      }
    },
    "required": [
      "playbook_id",
      "name"
    ]
  }
}

{
  "name": "update_mcp_server",
  "description": "Update a connected MCP or OpenAPI server's stored name, description, tools, resources, or transport. Requires playbooks:write or full permission. Use call_connected_tool to invoke a tool, and delete_mcp_server to disconnect. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "server_id": {
        "type": "string",
        "description": "Connected server UUID"
      },
      "name": {
        "type": "string",
        "description": "New display name"
      },
      "description": {
        "type": "string",
        "description": "New description"
      },
      "tools": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Updated tool definitions"
      },
      "resources": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Updated resource definitions"
      },
      "transport_type": {
        "type": "string",
        "enum": [
          "stdio",
          "http",
          "sse",
          "openapi"
        ],
        "description": "Connection type"
      },
      "transport_config": {
        "type": "object",
        "description": "Updated transport-specific configuration"
      }
    },
    "required": [
      "playbook_id",
      "server_id"
    ]
  }
}

{
  "name": "delete_mcp_server",
  "description": "Disconnect an MCP or OpenAPI server from this playbook. The remote server is not shut down; only this playbook's connection record is removed. Requires playbooks:write or full permission. Use update_mcp_server to change configuration without disconnecting. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "server_id": {
        "type": "string",
        "description": "Connected server UUID"
      }
    },
    "required": [
      "playbook_id",
      "server_id"
    ]
  }
}

{
  "name": "list_runs",
  "description": "List workflow runs for this playbook. Runs isolate canvas artifacts and execution context. Read-only. There is no get_run; this list returns the run records. Use create_run to start isolated canvas context and list_canvas to see documents in a run. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      }
    },
    "required": [
      "playbook_id"
    ]
  }
}

{
  "name": "create_run",
  "description": "Create a workflow run so this playbook can be applied immediately with isolated context and canvas artifacts. Requires canvas:write or full permission. Use list_runs to inspect existing runs (there is no get_run) and update_run to change status. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "Human-readable run name"
      },
      "context": {
        "type": "object",
        "description": "Initial execution context"
      }
    },
    "required": [
      "playbook_id",
      "name"
    ]
  }
}

{
  "name": "update_run",
  "description": "Update a workflow run's name, status, or context. Requires canvas:write or full permission. Use list_runs to find run_id (there is no get_run) and delete_run to remove the run and its canvas artifacts. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      },
      "name": {
        "type": "string",
        "description": "New run name"
      },
      "status": {
        "type": "string",
        "enum": [
          "active",
          "completed",
          "archived"
        ],
        "description": "New run status"
      },
      "context": {
        "type": "object",
        "description": "Replacement execution context"
      }
    },
    "required": [
      "playbook_id",
      "run_id"
    ]
  }
}

{
  "name": "delete_run",
  "description": "Permanently delete a workflow run and its isolated canvas artifacts. This cannot be undone. Requires canvas:write or full permission. Use update_run with status=archived to keep artifacts, and delete_playbook only when the whole playbook should go. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "run_id": {
        "type": "string",
        "description": "Workflow run UUID"
      }
    },
    "required": [
      "playbook_id",
      "run_id"
    ]
  }
}

{
  "name": "list_secrets",
  "description": "List all secret names and metadata in this playbook. Does not return values — secret values are never exposed to agents. Requires secrets:read or full permission. Use use_secret to make an authenticated HTTP request, store_secret to add a value, and rotate_secret to replace one. Do not use this tool expecting plaintext credentials. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "category": {
        "type": "string",
        "enum": [
          "api_key",
          "password",
          "token",
          "certificate",
          "connection_string",
          "general"
        ],
        "description": "Filter by category"
      }
    },
    "required": [
      "playbook_id"
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "secrets": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "category": {
              "type": "string"
            },
            "rotated_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "expires_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "last_used_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "use_count": {
              "type": "number"
            },
            "created_at": {
              "type": "string"
            },
            "updated_at": {
              "type": "string"
            }
          }
        }
      }
    },
    "required": [
      "secrets"
    ]
  }
}

{
  "name": "use_secret",
  "description": "Send a GET or HEAD request with a secret injected as a header, and return the response. The secret value is never returned to the agent — it is decrypted and used server-side only. Reads the remote API; it cannot change anything there, because only safe methods are accepted. The URL is chosen by the caller, so the target is whichever API the secret belongs to — see that API&#39;s own documentation for paths. Requires secrets:read or full permission. Example: use_secret({secret_name: &#39;OPENAI_API_KEY&#39;, url: &#39;https://api.openai.com/v1/models&#39;}) sends GET with &#39;Authorization: Bearer <key>&#39;. Use list_secrets to discover names, use_secret_write to send POST/PUT/PATCH/DELETE, and store_secret or rotate_secret to change a stored value. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "secret_name": {
        "type": "string",
        "description": "Name of the secret to use (e.g. OPENAI_API_KEY)"
      },
      "url": {
        "type": "string",
        "description": "The URL to send the HTTP request to"
      },
      "method": {
        "type": "string",
        "enum": [
          "GET",
          "HEAD"
        ],
        "description": "HTTP method (default: GET). For POST/PUT/PATCH/DELETE use use_secret_write."
      },
      "header_name": {
        "type": "string",
        "description": "Header name to inject the secret into (default: Authorization)"
      },
      "header_prefix": {
        "type": "string",
        "description": "Prefix before the secret value (default: &#39;Bearer &#39;). Use empty string for raw value."
      },
      "extra_headers": {
        "type": "object",
        "description": "Additional headers (e.g. {\"Accept\": \"application/json\"})"
      },
      "timeout_ms": {
        "type": "number",
        "description": "Request timeout in milliseconds (default: 30000, max: 60000)"
      }
    },
    "required": [
      "playbook_id",
      "secret_name",
      "url"
    ]
  }
}

{
  "name": "use_secret_write",
  "description": "Send a POST, PUT, PATCH or DELETE request with a secret injected as a header, and return the response. The secret value is never returned to the agent — it is decrypted and used server-side only. This changes state in the remote API and cannot be undone from here. The URL is chosen by the caller, so the target is whichever API the secret belongs to — see that API's own documentation for paths and payloads. Requires secrets:read or full permission. Use use_secret for GET and HEAD, list_secrets to discover names, and store_secret or rotate_secret to change a stored value rather than send a request. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "secret_name": {
        "type": "string",
        "description": "Name of the secret to use (e.g. DEPLOY_API_KEY)"
      },
      "url": {
        "type": "string",
        "description": "The URL to send the HTTP request to"
      },
      "method": {
        "type": "string",
        "enum": [
          "POST",
          "PUT",
          "PATCH",
          "DELETE"
        ],
        "description": "HTTP method (default: POST). For GET/HEAD use use_secret."
      },
      "header_name": {
        "type": "string",
        "description": "Header name to inject the secret into (default: Authorization)"
      },
      "header_prefix": {
        "type": "string",
        "description": "Prefix before the secret value (default: 'Bearer '). Use empty string for raw value."
      },
      "body": {
        "type": "object",
        "description": "JSON request body (for POST/PUT/PATCH)"
      },
      "extra_headers": {
        "type": "object",
        "description": "Additional headers (e.g. {\"Content-Type\": \"application/json\"})"
      },
      "timeout_ms": {
        "type": "number",
        "description": "Request timeout in milliseconds (default: 30000, max: 60000)"
      }
    },
    "required": [
      "playbook_id",
      "secret_name",
      "url"
    ]
  }
}

{
  "name": "store_secret",
  "description": "Store a new encrypted secret. The value is encrypted with AES-256-GCM using a per-user derived key and never stored or returned in plaintext. Requires secrets:write or full permission. Use rotate_secret to replace an existing value and list_secrets to confirm the name. Do not use this to send an authenticated request; use use_secret. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "Secret name (letters, numbers, hyphens, underscores)"
      },
      "value": {
        "type": "string",
        "description": "The secret value to encrypt and store"
      },
      "description": {
        "type": "string",
        "description": "What this secret is used for"
      },
      "category": {
        "type": "string",
        "enum": [
          "api_key",
          "password",
          "token",
          "certificate",
          "connection_string",
          "general"
        ],
        "description": "Secret type (default: general)"
      },
      "expires_at": {
        "type": "string",
        "description": "ISO 8601 expiration date (optional)"
      }
    },
    "required": [
      "playbook_id",
      "name",
      "value"
    ]
  }
}

{
  "name": "rotate_secret",
  "description": "Rotate an existing secret with a new value. The old value is permanently replaced and cannot be recovered. Requires secrets:write or full permission. Use store_secret to create a name that does not exist yet, and delete_secret to remove the secret entirely. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "Secret name to rotate"
      },
      "value": {
        "type": "string",
        "description": "New secret value"
      }
    },
    "required": [
      "playbook_id",
      "name",
      "value"
    ]
  }
}

{
  "name": "delete_secret",
  "description": "Permanently delete a secret. Cannot be undone. Requires secrets:write or full permission. Use rotate_secret to replace the value without removing the name, and list_secrets to confirm the name first. This does not revoke the credential at the upstream provider. Pass playbook_id as the UUID or GUID of the playbook this call should target.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playbook_id": {
        "type": "string",
        "description": "UUID or GUID of the target playbook"
      },
      "name": {
        "type": "string",
        "description": "Secret name to delete"
      }
    },
    "required": [
      "playbook_id",
      "name"
    ]
  }
}