create_external_share
Creates a public share link for content, with optional expiration. Accessible by anyone without a Marcora account. Workflow: 1) Get content_id from list_content. 2) Optionally provide expires_at as a Unix timestamp to limit access duration. 3) Returns a ready-to-use share_link URL that is accessible publicly, but won't be indexed by search engines.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"share_link":{"type":"string","description":"Public URL (https://app.marcora.ai/s/<token>) anyone can use to view the content"}},"required":["share_link"]}
create_plan
Create a new plan for the authenticated user's active team. Title is the only required field.
Input roles:
- title: Required. The one-line summary of the content intent.
- description: Optional elaboration. Becomes a tooltip in the plans list.
- due_date: ISO date YYYY-MM-DD.
- prompt: The actual content prompt — pre-populates the content creation form when Generate is clicked.
- blueprint_id: UUID of the content blueprint/template to use.
- project_id: Project UUID to associate this plan with.
- category_id: Content category integer ID.
- reference_document_ids: Array of content UUID strings to associate as reference material.
- context_collection_ids: Array of integer collection IDs to pre-attach.
- targeting_dimension_ids: Array of integer dimension option IDs to pre-attach.
- source: "cora_requested" (default — use when user explicitly asked) | "cora_proactive" (use when surfacing an unprompted suggestion) | "user_added" | "workflow" | "playbook". NEVER use "workflow" or "playbook" from interactive Cora sessions.
- source_metadata: Object. Include {cora_session_id, cora_message_snippet} for cora_proactive / cora_requested. For workflow runs use {workflow_template_id, workflow_run_id, workflow_name, run_timestamp}. Immutable after creation.
- assigned_to: Optional integer user ID. Defaults to the calling user. Must be a current team member.
- plan_uuid: Optional client-supplied UUIDv4 for optimistic creates. Server validates format + uniqueness; rejects collisions with InputError. Server generates if omitted.
Starting stage is determined by source AUTOMATICALLY — you do NOT control it directly:
- user_added / cora_requested / playbook → Accepted (actionable immediately)
- cora_proactive → Suggested (needs user accept)
- workflow → Suggested (default) or Accepted if workflow_template.plan_starting_stage = 'Accepted'
Usage patterns:
- **Dedupe first:** Always call list_plans with project_id filter before creating multiple plans for the same project in one turn, to avoid duplicates. If a matching plan exists in Accepted/Suggested, offer to update it instead.
- **Batch correlation:** When creating multiple plans in one user turn, set source_metadata.batch_id (a client-generated UUID) to correlate them. After creation, respond with a deep link to the filtered plans view for that batch_id.
- **Note:** create_plan echoes input reference docs without filtering. If you need the canonical filtered reference_documents array, call get_plan after create.
Errors:
- InputError: title is required — title was omitted or empty.
- InputError: source must be one of [user_added, cora_proactive, cora_requested, workflow, playbook].
- InputError: plan_uuid already exists — client-supplied UUID collides with an existing plan in this team.
- InputError: invalid plan_uuid format — supplied UUID is not a valid UUIDv4.
- InputError: assigned_to is not a member of the team — target user is not a current team member.
- AccessDenied — JWT does not resolve to a valid team context.
---OUTPUT_SCHEMA---
{
"type": "object",
"required": ["plan_uuid", "id", "team_id", "created_by", "assigned_to", "stage", "source", "title", "created_at", "updated_at"],
"properties": {
"plan_uuid": { "type": "string", "description": "UUIDv4 — the external-facing identifier. Use this for all subsequent calls." },
"id": { "type": "integer", "description": "Internal integer PK; not exposed externally." },
"team_id": { "type": "integer" },
"created_by": { "type": "integer" },
"assigned_to": { "type": "integer" },
"stage": { "type": "string", "enum": ["Suggested", "Accepted", "In_Process", "Complete", "Dismissed"] },
"source": { "type": "string" },
"source_metadata": { "type": ["object", "null"] },
"title": { "type": "string" },
"description": { "type": ["string", "null"] },
"due_date": { "type": ["string", "null"] },
"prompt": { "type": ["string", "null"] },
"blueprint_id": { "type": ["string", "null"] },
"project_id": { "type": ["string", "null"] },
"category_id": { "type": ["integer", "null"] },
"produced_content_id": { "type": ["string", "null"] },
"reference_documents": { "type": "array" },
"context_collections": { "type": "array" },
"targeting_dimensions": { "type": "array" },
"created_at": { "type": "integer" },
"updated_at": { "type": "integer" },
"completed_at": { "type": ["integer", "null"] },
"dismissed_at": { "type": ["integer", "null"] }
}
}
create_project
Use this tool to create a new project for organizing content and context into a workstream.
Projects group related documents and can include project-specific context items.
Workflow:
1) Provide a name for the project.
2) Optionally set visibility to "team" or "private" (default: team).
3) Optionally provide `project_brief_details` to auto-generate a project brief document. If you do, the response will include a `project_brief` object containing the brief's `content_id` — use that with `update_content` later to edit or finalize the brief.
4) Use the returned `project_id` with `create_content` to associate new content with this project.
---OUTPUT_SCHEMA---
{
"type": "object",
"properties": {
"project_id": {"type": "string", "format": "uuid", "description": "Project identifier."},
"name": {"type": "string", "description": "Project name."},
"link_url": {"type": "string", "format": "uri", "description": "Direct URL to view/open this project in Marcora."},
"project_brief": {
"type": ["object", "null"],
"description": "Present (non-null) only when `project_brief_details` was supplied. Pass `content_id` to update_content / get_content later.",
"properties": {
"name": {"type": "string", "description": "Brief document name."},
"content_id": {"type": "string", "format": "uuid", "description": "Content UUID of the brief."}
}
}
},
"required": ["project_id", "name", "link_url"]
}
create_workflow
Create a new workflow template for the user's active team. Workflows start as status="draft"; activate them via update_workflow once the user confirms.
Input roles:
- name: Human-readable name. Confirm with the user before creating.
- description: One or two sentences. Becomes part of the runner's system prompt.
- steps: Ordered list. Each step should be specific enough that a fresh agent can do it without follow-up questions.
- inputs: Declare what the workflow needs (e.g., topic, date_range). For scheduled runs these are resolved from trigger bindings.
- allowed_tools: Narrow allowlist. Prefer tight allowlists for scheduled runs.
- tags: Optional.
- schedule_config: Include ONLY if the user explicitly wants scheduling. Shape: {"frequency": "daily"|"weekly"|"hourly", "interval_hours": N, "timezone": "UTC"}.
Usage patterns:
- Always create as draft.
- Before creating, check list_workflows with a `search:` filter for duplicate names.
- For scheduled workflows that process entities (e.g., "new content items since last run"), set up a since_last_run input binding via the trigger.
- The returned `id` is a UUID string. Use it as `workflow_id` in get_workflow / update_workflow / run_workflow / get_workflow_runs.
---OUTPUT_SCHEMA---
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["id", "name", "status", "team_id", "created_at", "link_url"],
"properties": {
"id": {"type": "string", "format": "uuid", "description": "Workflow UUID. Use as workflow_id in other workflow tools."},
"team_id": {"type": "integer"},
"created_by_user_id": {"type": "integer"},
"name": {"type": "string"},
"description": {"type": "string"},
"status": {"type": "string", "enum": ["draft", "active", "archived"]},
"inputs": {"type": "object"},
"steps": {"type": "array"},
"allowed_tools": {"type": "array"},
"tags": {"type": "array"},
"created_at": {"type": "integer"},
"updated_at": {"type": "integer"},
"link_url": {"type": "string", "format": "uri", "description": "Direct URL to view this workflow in Marcora."}
}
}
finalize_blueprint_draft
*SYNCHRONOUS — takes 1-3 minutes. This is expected; do not retry or assume an error.*
Use this tool to finalize (publish) a previously created blueprint draft into a full, usable blueprint. This is the final step in the draft workflow:
1) create_blueprint_draft — generates an AI-assisted draft the user can review/edit in the app
2) User reviews the draft at the link_url
3) finalize_blueprint_draft — converts the reviewed draft into a real blueprint
After finalizing, use the returned blueprint_uuid with create_content (passing it as blueprint_uuid) to generate content from this blueprint.
If you don't need the review step, use create_blueprint instead to create a blueprint directly.
---OUTPUT_SCHEMA---
{
"type": "object",
"properties": {
"blueprint_uuid": {
"type": "string",
"format": "uuid",
"description": "Unique identifier — use as blueprint_uuid in create_content."
},
"name": {
"type": "string",
"description": "Blueprint name."
},
"link_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to view/edit this blueprint in Marcora."
},
"source_content": {
"type": "string",
"description": "The template content from the finalized draft."
},
"reference_content": {
"type": "string",
"description": "AI-polished reference version of the template content."
},
"blueprint_dna": {
"type": "string",
"description": "AI-generated analysis of the template structure, tone, and section descriptions."
},
"input_instructions": {
"type": "string",
"description": "AI-generated guidance for users on what context to provide when generating from this blueprint."
},
"summary": {
"type": "string",
"description": "AI-generated summary of what this blueprint produces."
},
"category": {
"type": "object",
"description": "Content category this blueprint belongs to.",
"properties": {
"id": {
"type": "integer",
"description": "Category ID."
},
"name": {
"type": "string",
"description": "Category name."
}
},
"required": ["id", "name"]
},
"team_visibility": {
"type": "string",
"description": "Visibility within your team (e.g. team, private)."
},
"created_at": {
"type": "integer",
"description": "Unix timestamp of creation."
}
},
"required": ["blueprint_uuid", "name", "link_url"]
}
get_blueprint
Retrieves the full details of a specific blueprint by its UUID. Returns the blueprint's content, AI-generated analysis, and metadata.
Use list_blueprints to list all available blueprints and find the blueprint_uuid.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"blueprint_uuid":{"type":"string","format":"uuid","description":"Unique blueprint identifier."},"name":{"type":"string","description":"Blueprint name."},"source_content":{"type":"string","description":"The original template content."},"reference_content":{"type":"string","description":"AI-polished reference version of the template content."},"blueprint_dna":{"type":"string","description":"AI-generated analysis of the template structure, tone, and section descriptions."},"input_instructions":{"type":"string","description":"AI-generated guidance for users on what context to provide when generating from this blueprint."},"summary":{"type":"string","description":"AI-generated summary of what this blueprint produces."},"category":{"type":["object","null"],"description":"Content category, or null.","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"team_visibility":{"type":"string","description":"Visibility within your team (e.g. team, private)."},"exchange_visibility":{"type":"string","description":"Community exchange visibility (e.g. public, none)."},"created_at":{"type":"integer","description":"Unix timestamp of creation."},"web_url":{"type":"string","description":"Direct URL to view this blueprint in Marcora."}},"required":["blueprint_uuid","name"]}
get_brand_foundation
Returns the team's Brand Foundation — the foundational brand and company information that guides all AI-generated content. The four elements are:
- **company_overview** — general information about the company
- **brand_voice** — tone, core values, mission, and personality
- **writing_style** — language complexity, sentence structure, formatting preferences, CTA style
- **writing_examples** — sample content demonstrating the team's distinctive voice (free-form structure; users organize this however they like)
By default returns all four elements. Pass `elements` to scope the response to a subset.
The response is structured JSON — paste it directly into a downstream AI prompt (modern LLMs read JSON fine) or template-string the fields into markdown if you prefer. Empty string is returned for any element the team has not filled out yet.
**Companion tool:** `update_brand_foundation` to overwrite an element's content.
Note: `create_content`, `create_plan`, and Marcora's in-app content generation system automatically pull Brand Foundation in — you only need this tool when you're operating *outside* those flows (e.g. providing Brand Foundation context to an external AI agent).
---OUTPUT_SCHEMA---
{"type":"object","properties":{"company_overview":{"type":"string","description":"Markdown content for Company Overview. Empty string if not set. Only present if requested via elements."},"brand_voice":{"type":"string","description":"Markdown content for Brand Voice. Empty string if not set. Only present if requested via elements."},"writing_style":{"type":"string","description":"Markdown content for Writing Style. Empty string if not set. Only present if requested via elements."},"writing_examples":{"type":"string","description":"Markdown content for Writing Examples. Free-form structure — whatever the user has saved. Empty string if not set. Only present if requested via elements."}}}
get_community_blueprint_details
Get the full details for a specific community blueprint, including its complete content (markdown), content description/style guide, and contributor information.
Use the 'id' (blueprint_exchange_id) returned by list_community_blueprints. The 'content' field contains the full example document in markdown. The 'content_description' describes the template structure and style guidelines.
Pass the 'id' to import_community_blueprint to add this blueprint to the current team.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Blueprint exchange ID. Pass to import_community_blueprint."},"slug":{"type":"string","description":"URL-friendly identifier."},"name":{"type":"string","description":"Blueprint name."},"summary":{"type":"string","description":"What this blueprint produces."},"content":{"type":"string","description":"Full example document content in markdown."},"content_description":{"type":"string","description":"Template structure and style guidelines."},"input_instructions":{"type":"string","description":"Guidance for what context to provide when generating from this blueprint."},"is_featured":{"type":"boolean","description":"Whether this blueprint is featured by Marcora."},"visibility":{"type":"string","description":"Exchange visibility status (e.g. public)."},"contributor_name":{"type":"string","description":"Name of the blueprint creator."},"contributor_job_title":{"type":"string","description":"Job title of the blueprint creator."},"contributor_company":{"type":"string","description":"Company of the blueprint creator."},"suggested_content_type":{"type":"string","description":"Suggested content type name for this blueprint."}},"required":["id","name","content"]}
get_content
Retrieves the full markdown body of a specific content document by its content_id (UUID).
**Use this ONLY when you need to read the content body to answer the user's question** — for example: "summarize what my latest case study says about pricing," "what's the main argument in my Q3 launch blog?", or "does this messaging doc mention HIPAA?". The user already has access to view the content in Marcora via its link, so reading the body yourself is only useful when you need to answer something specific about it.
**Do NOT call this after `create_content` (or after `get_generation_status` returns "completed") just to "show the user what was generated."** The user opens the content in Marcora via the link_url — they review it themselves. Marcora hands them the link; the user does the reading.
---OUTPUT_SCHEMA---
{
"type": "object",
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"description": "Content identifier."
},
"name": {
"type": "string",
"description": "Content name."
},
"content": {
"type": "string",
"description": "Full document content in markdown format."
},
"visibility": {
"type": "string",
"description": "Visibility setting (e.g. private, team)."
},
"stage": {
"type": "string",
"description": "Enumeration of in_progress or ready."
},
"category": {
"type": ["object", "null"],
"description": "Content category, or null if not categorized.",
"properties": {
"id": {
"type": "integer",
"description": "Category ID."
},
"name": {
"type": "string",
"description": "Category name."
}
}
},
"link_url": {
"type": "string",
"description": "Direct URL to view this content in Marcora."
}
},
"required": ["content_id", "name", "content"]
}
get_context_item
Fetches the full markdown content and metadata of a single context item by ID.
Use this when you need the actual content of a context item — list_context_items only returns content_intro (a short truncation). The IDs you pass here can come from list_context_items, get_project(project_id).context_items, or get_relevant_context (which returns context_item_ids of parent items for matched chunks).
Authorization: the item must belong to your team. Items in private collections (where you are not the creator) and items in private projects (where you are not a member) return 404 — same as items that do not exist.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"content":{"type":"string","description":"Full markdown content of the context item."},"content_intro":{"type":"string"},"content_type":{"type":"string"},"word_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":["integer","null"]},"added_by":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"relevancy_processed_status":{"type":"string"},"collection_id":{"type":["integer","null"]},"project_id":{"type":["string","null"],"format":"uuid"},"link_url":{"type":"string","description":"URL to view this context item in the Marcora web app."}},"required":["id","name","content","link_url"]}
get_generation_status
Check the status of an async content generation. Call this after create_content (with blueprint_uuid), which returns a generation_id.
Typical workflow:
1. Call create_content with a blueprint_uuid → get generation_id.
2. Wait 2-4 minutes (generation takes time).
3. Call this tool with the generation_id to check progress.
4. If status is not "completed", wait and retry.
5. When complete, the response includes `content.link_url` — pass that link directly to the user. They open it in Marcora to read/edit/share. **You do NOT need to call get_content** to fetch the body — Marcora hands the link to the user; the user reviews the content themselves.
Only call get_content if the user later asks a question that requires you to read the content body to answer (e.g., "summarize what my latest case study says about pricing").
---OUTPUT_SCHEMA---
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Generation status (e.g. pending, gathering context, processing, completed, failed)."
},
"generation_id": {
"type": "string",
"description": "The generation ID being checked."
},
"content": {
"type": "object",
"description": "Content summary (present when status is completed). The link_url is what you should pass to the user — do NOT call get_content unless the user later asks a question requiring the body text.",
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"description": "Content ID. Only needed if the user later asks a question that requires reading the content body (then pass to get_content)."
},
"name": {
"type": "string",
"description": "Content name."
},
"blueprint_id": {
"type": "integer",
"description": "Blueprint used to generate this content."
},
"link_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to view/open the content. Pass this to the user — they review it in Marcora."
}
}
}
}
}
get_plan
Fetch a single plan by UUID including all linked parameters and metadata.
Input roles:
- plan_uuid: The UUID string from a create_plan response or a list_plans result. Use plan_uuid, not the integer id.
Usage patterns:
- **Always call get_plan before update_plan** to read current state and avoid overwriting fields with stale values.
- Use _produced_content to determine whether the plan has linked content (null = no content yet).
- Use _source_metadata_resolved for tooltip / inline attribution display without extra lookups.
- Before calling create_content with plan_id, verify the plan is NOT in Complete stage. If stage = Complete, ask the user whether to re-open the plan (update_plan target_stage: 'Accepted') before generating again.
- reference_documents is filtered to documents readable by the current user — do not assume the full list is returned if the team has cross-team sharing enabled.
Errors:
- NotFound — plan_uuid doesn't exist or is not visible to your team. Cross-team plans return NotFound, not AccessDenied.
---OUTPUT_SCHEMA---
{
"type": "object",
"required": ["plan"],
"properties": {
"plan": {
"type": "object",
"properties": {
"plan_uuid": { "type": "string" },
"id": { "type": "integer", "description": "Internal PK; do not use externally." },
"team_id": { "type": "integer" },
"created_by": { "type": "integer" },
"assigned_to": { "type": "integer" },
"stage": { "type": "string", "enum": ["Suggested", "Accepted", "In_Process", "Complete", "Dismissed"] },
"source": { "type": "string", "enum": ["user_added", "cora_proactive", "cora_requested", "workflow", "playbook"] },
"source_metadata": { "type": ["object", "null"] },
"title": { "type": "string" },
"description": { "type": ["string", "null"] },
"due_date": { "type": ["string", "null"] },
"prompt": { "type": ["string", "null"] },
"blueprint_id": { "type": ["string", "null"] },
"project_id": { "type": ["string", "null"] },
"category_id": { "type": ["integer", "null"] },
"produced_content_id": { "type": ["string", "null"] },
"created_at": { "type": "integer" },
"updated_at": { "type": "integer" },
"completed_at": { "type": ["integer", "null"] },
"dismissed_at": { "type": ["integer", "null"] },
"reference_documents": { "type": "array", "description": "Content UUIDs accessible to the current user." },
"context_collections": { "type": "array" },
"targeting_dimensions": { "type": "array" },
"_produced_content": { "type": ["object", "null"], "description": "The linked content object or null. When non-null contains at minimum: content_id, name, stage, visibility." },
"_source_metadata_resolved": { "type": ["object", "null"], "description": "Denormalized tooltip data (workflow_name resolved fresh; cora snippet fields). Null if source=user_added." }
}
}
}
}
get_project
Returns details for a specific project including its members, documents, context items, and (when set) a top-level `project_brief` shortcut for editing the project's brief via `update_content`.
Use `list_projects` to discover available projects and find the `project_id`.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Project UUID."},"name":{"type":"string","description":"Project name."},"visibility":{"type":"string","description":"Visibility (e.g. team, private)."},"status":{"type":"string","description":"Project status (e.g. active, archived)."},"created_at":{"type":"integer","description":"Unix timestamp of creation."},"members":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer","description":"User ID."},"role":{"type":"string","description":"Role in project (e.g. owner, member)."},"name":{"type":"string","description":"Member name."},"email":{"type":"string","description":"Member email."}}}},"documents":{"type":"array","items":{"type":"object","properties":{"content_id":{"type":"string","format":"uuid","description":"Content UUID — pass to get_content or update_content."},"name":{"type":"string","description":"Content name."},"visibility":{"type":"string","description":"Visibility setting."},"is_ready":{"type":"boolean","description":"Whether generation is complete."},"category":{"type":["object","null"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"description":"Content category, or null."},"purpose":{"type":"string","description":"Role of content in project (e.g. supporting)."},"in_project_context":{"type":"boolean","description":"Whether included in project context for AI generation."},"web_url":{"type":"string","description":"Direct URL to view this content in Marcora."}}}},"project_brief":{"type":["object","null"],"description":"The project's pinned brief document, if one is set. Same shape as create_project's project_brief field. Pass content_id to update_content / get_content to edit or read the brief.","properties":{"name":{"type":"string"},"content_id":{"type":"string","format":"uuid"}}},"context_items":{"type":"array","description":"Context items associated with this project."}},"required":["id","name"]}
get_relevant_context
Searches the team's context library and returns the most relevant chunks for a given prompt.
**When to use this tool:** Use it ONLY when the user is asking a question or ideating — i.e., when YOU need to read context yourself to answer them. Examples:
- "What do we have on competitor X?"
- "Remind me what our positioning is for healthcare?"
- "Have we written anything about our new pricing model yet?"
- "I'm thinking about a campaign — what context do we already have I could draw on?"
**When NOT to use this tool:** Do NOT call this before `create_content`. The `create_content` tool internally pulls all relevant context (Brand Foundation + Reference Library via relevancy scoring + Project Context if `project_id` is set + any explicit Context Collections you pass). Pre-fetching context yourself just to pass it along is wasted work — `create_content` does it automatically.
Pass a descriptive prompt to get the best matching context. Optionally scope results to specific collections, a project, or targeting dimensions. Use context_rag_ids to exclude previously retrieved chunks when paginating for additional context.
Returns up to 10 context chunks per call.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"relevant_context":{"type":"string","description":"Concatenated relevant context text from matched chunks."},"context_rag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Chunk IDs returned. Pass these back in context_rag_ids to exclude from future searches (pagination)."},"context_item_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Parent context item IDs that the chunks belong to."}}}
get_workflow_runs
Inspect workflow run history. Two modes controlled by run_id presence:
Input roles:
- workflow_id: UUID string of the workflow.
- run_id: UUID string. If present → single-run detail with step logs and tool call logs. If absent → paginated list of runs.
- status: list-mode filter. Ignored in single mode.
- page / per_page: list-mode pagination.
Usage patterns:
- When the user asks "did my workflow run?": call with just workflow_id (list mode) and look at items[0].status + items[0].completed_at.
- When the user asks "what did that run do?": call with workflow_id + run_id (single mode) and read _step_logs and _tool_call_logs.
- When troubleshooting failures: filter list mode by status="failed", then pull each detail.
- Each run's `id` is a UUID string. The `link_url` on each run points to its detail page in Marcora.
---OUTPUT_SCHEMA---
{
"$schema": "http://json-schema.org/draft-07/schema#",
"oneOf": [
{
"type": "object",
"description": "List mode (run_id omitted).",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid"},
"workflow_template_id": {"type": "string", "format": "uuid"},
"status": {"type": "string"},
"link_url": {"type": "string", "format": "uri"}
}
}
},
"itemsTotal": {"type": "integer"}
}
},
{
"type": "object",
"description": "Single-run mode (run_id supplied).",
"properties": {
"id": {"type": "string", "format": "uuid"},
"workflow_template_id": {"type": "string", "format": "uuid"},
"status": {"type": "string"},
"_step_logs": {"type": "array"},
"_tool_call_logs": {"type": "array"},
"link_url": {"type": "string", "format": "uri"}
}
}
]
}
get_workflow
Fetch one workflow's full definition plus triggers and latest run. Always use this before update_workflow to see the current field values — partial updates clobber unspecified keys.
Input roles:
- workflow_id: UUID string of the workflow to fetch.
Usage patterns:
- Before update_workflow: call get_workflow, read the current `steps` / `allowed_tools` / `inputs`, then construct your update payload with those existing values preserved for any field you aren't changing.
- To show a workflow's schedule: inspect `_triggers[0].schedule_config` and `_triggers[0].is_enabled`.
- To show last run outcome: inspect `_latest_run.status` + `_latest_run.completed_at`.
---OUTPUT_SCHEMA---
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["workflow"],
"properties": {
"workflow": {
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid"},
"name": {"type": "string"},
"status": {"type": "string"},
"steps": {"type": "array"},
"inputs": {"type": "object"},
"allowed_tools": {"type": "array"},
"_triggers": {"type": "array"},
"_latest_run": {"type": ["object", "null"], "description": "Most recent run, or null. When present, includes its own link_url."},
"link_url": {"type": "string", "format": "uri", "description": "Direct URL to view this workflow in Marcora."}
}
}
}
}
import_community_blueprint
Use this tool to import a blueprint from the Marcora community exchange into your team's library. Once imported, use it like any of your own blueprints to generate content. Workflow: 1) Use list_community_blueprints to browse and find a blueprint. 2) Copy the blueprint_exchange_id. 3) Call this tool to import it. 4) Use list_blueprints to confirm it appears in your library. 5) Use create_content with the returned uuid as blueprint_uuid to generate content.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"id":{"type":"integer","description":"Blueprint record ID"},"uuid":{"type":"string","format":"uuid","description":"Unique identifier - use as blueprint_uuid in create_content"},"name":{"type":"string","description":"Blueprint name"},"content":{"type":"string","description":"Blueprint template content"},"imported_exchange_id":{"type":"string","format":"uuid","description":"Reference to original community blueprint"},"team_visibility":{"type":"string","description":"Visibility within your team"},"created_at":{"type":"integer","description":"Unix timestamp of import"}}}
list_blueprints
Get all blueprints in your team's library as a flat list. Each blueprint includes its content category. Use the returned blueprint_uuid with create_content (passing it as blueprint_uuid) to generate content.
---OUTPUT_SCHEMA---
{
"type": "array",
"description": "All blueprints in your team's library, flattened across content categories.",
"items": {
"type": "object",
"properties": {
"blueprint_uuid": {
"type": "string",
"format": "uuid",
"description": "Unique identifier — pass as blueprint_uuid to create_content."
},
"name": {
"type": "string",
"description": "Blueprint name."
},
"input_instructions": {
"type": "string",
"description": "Guidance on what context to provide when generating from this blueprint."
},
"team_visibility": {
"type": "string",
"description": "Visibility within your team (e.g. team, private)."
},
"exchange_visibility": {
"type": "string",
"description": "Community exchange visibility (e.g. public, none)."
},
"content_count": {
"type": "integer",
"description": "Number of content items generated from this blueprint."
},
"created_at": {
"type": "integer",
"description": "Unix timestamp of creation."
},
"category": {
"type": "object",
"description": "Content category this blueprint belongs to.",
"properties": {
"id": {
"type": "integer",
"description": "Category ID (matches list_content_categories)."
},
"name": {
"type": "string",
"description": "Category name."
}
}
},
"web_url": {
"type": "string",
"description": "Direct URL to view this blueprint in Marcora."
}
},
"required": ["blueprint_uuid", "name", "category"]
}
}
list_community_blueprints
Browse community blueprints available for import. Returns a list of blueprints shared by Marcora users, including name, summary, contributor info, and category.
Use the returned 'id' with get_community_blueprint_details to view the full blueprint content before importing.
---OUTPUT_SCHEMA---
{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Blueprint exchange ID. Pass to get_community_blueprint_details or import_community_blueprint."},"slug":{"type":"string","description":"URL-friendly identifier."},"name":{"type":"string","description":"Blueprint name."},"summary":{"type":"string","description":"What the blueprint produces."},"is_featured":{"type":"boolean","description":"Whether this blueprint is featured."},"input_instructions":{"type":"string","description":"Guidance for the user on what context to provide when generating from this blueprint."},"visibility":{"type":"string","description":"Exchange visibility status."},"contributor_name":{"type":"string","description":"Name of the blueprint creator."},"contributor_company":{"type":"string","description":"Company of the blueprint creator."},"category":{"type":"string","description":"Content category name."},"category_short":{"type":"string","description":"Short category label."}},"required":["id","name","summary"]}}
list_content_categories
Returns all content categories available to your team. Categories organize blueprints and content by type (e.g. GTM Messaging, Website & Blog, Sales & Partner Materials).
Use the 'id' as the category_id when creating blueprints (create_blueprint) or content (create_content).
---OUTPUT_SCHEMA---
{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID. Pass to create_blueprint or create_blueprint_draft as category_id."},"name":{"type":"string","description":"Category name (e.g. GTM Messaging)."}},"required":["id","name"]}}
list_content
Returns all content visible to the current user as a single unified array. Content created from scratch and from blueprints are merged with consistent field names.
Use content_id with get_content to retrieve full content. Use create_external_share to share content externally.
---OUTPUT_SCHEMA---
{
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Content name."
},
"content_id": {
"type": "string",
"format": "uuid",
"description": "Content UUID. Pass to get_content or create_external_share."
},
"visibility": {
"type": "string",
"description": "Visibility setting (e.g. private, team)."
},
"stage": {
"type": "string",
"description": "Enum options for in_progress or ready"
},
"category": {
"type": ["object", "null"],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"description": "Content category, or null if uncategorized."
},
"created_by": {
"type": "string",
"description": "Name of the creator."
},
"projects": {
"type": "array",
"items": {
"type": "string"
},
"description": "Project names this content belongs to."
},
"web_url": {
"type": "string",
"description": "Direct URL to view this content in Marcora."
}
},
"required": ["name", "content_id"]
}
}
list_context_collections
Returns all context collections accessible to the current user. Collections organize reference materials (context items) that inform AI-generated content.
Use the 'id' with add_context to add items to a specific collection, or pass collection_ids to get_relevant_context for targeted context retrieval.
Each item includes a link_url that opens the collection directly in the Marcora web app.
---OUTPUT_SCHEMA---
{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Collection ID. Pass to add_context or get_relevant_context."},"name":{"type":"string","description":"Collection name."},"description":{"type":"string","description":"Collection description."},"is_private":{"type":"boolean","description":"Whether this collection is private to the creator."},"item_count":{"type":"integer","description":"Number of context items in this collection."},"link_url":{"type":"string","description":"URL to view this collection in the Marcora web app."}},"required":["id","name"]}}
list_context_items
Lists context items from the team's context library.
By default returns ALL context items the user can see (across projects, collections, and the reference library). Set reference_library_only=true to return only items that are NOT in any project or collection — these are the items shown in the "Reference Library" section of the Marcora web app.
Each returned item carries its own collection_id and project_id (both nullable), so you always know where it lives. To get the full markdown content of any item, pass its id to get_context_item.
Privacy: items in private collections (where you are not the creator) and items in private projects (where you are not a member) are filtered out — they will not appear in the response.
Other ways to discover context-item IDs:
- get_project(project_id).context_items — items attached to a specific project.
- get_relevant_context — returns context_item_ids of parent items for matched chunks.
---OUTPUT_SCHEMA---
{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Context item ID. Pass to get_context_item to fetch full markdown."},"name":{"type":"string"},"content_intro":{"type":"string","description":"Short truncation of the content for previews."},"content_type":{"type":"string"},"word_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":["integer","null"]},"added_by":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"relevancy_processed_status":{"type":"string"},"collection_id":{"type":["integer","null"],"description":"Collection this item lives in, or null."},"project_id":{"type":["string","null"],"format":"uuid","description":"Project this item is associated with, or null."}},"required":["id","name"]}}
list_plans
List plans for the authenticated user's active team. Supports rich filters for discovery and deduplication. Returns paginated summary rows — use get_plan for full detail.
Input roles:
- stage: array of stage enum values. Use UNDERSCORE form `In_Process`. Allowed: Suggested, Accepted, In_Process, Complete, Dismissed. Omit to return all stages.
- source: array of source enum values. Allowed: user_added, cora_proactive, cora_requested, workflow, playbook. Use ["workflow"] to show only workflow-generated plans.
- project_id: filter to plans for a specific project (project UUID string).
- category_id: filter to plans in a category (integer).
- assignee_scope: "me" (default) | "created_by_me" | "all_visible".
- due_before / due_after: ISO date strings (YYYY-MM-DD). Pair for an "upcoming week" view.
- search_text: substring match on plan title.
- sort: "due_asc_nulls_last" (default — best for action planning) | "created_desc" (newest first).
- page / per_page: pagination. Default per_page=20, max=100.
Usage patterns:
- **Dedupe before create:** Before creating a plan for a project, call list_plans with project_id filter. If a matching plan already exists in Accepted or Suggested, offer to update it rather than creating a duplicate.
- **Workflow-generated triage:** source=["workflow"] + stage=["Suggested"] surfaces workflow suggestions awaiting user review.
- **Upcoming week view:** due_before = (today + 7 days, YYYY-MM-DD), sort = "due_asc_nulls_last".
- **Finding all plans I created:** assignee_scope = "created_by_me".
Known limitations (accepted by the tool but currently no-op):
- due_before / due_after: filter accepted but does not apply yet.
- search_text: filter accepted but does not apply yet.
- Multi-value stage[]/source[]: only the FIRST array element is honored. Pass single-value arrays to be safe.
---OUTPUT_SCHEMA---
{
"type": "object",
"description": "Paginated plan summary results.",
"properties": {
"items": {
"type": "array",
"description": "Array of plan summary objects. Each item: plan_uuid, title, stage, source, assigned_to, created_by, due_date, produced_content_id, created_at, updated_at."
},
"itemsTotal": { "type": "integer" },
"curPage": { "type": "integer" },
"nextPage": { "type": ["integer", "null"] },
"prevPage": { "type": ["integer", "null"] }
}
}
list_projects
Returns all projects visible to the current user. Projects organize content into workstreams.
Use the 'id' with get_project to retrieve project details, or pass project_id when creating content to associate it with a project.
---OUTPUT_SCHEMA---
{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Project ID. Pass to get_project or use when creating content."},"name":{"type":"string","description":"Project name."},"link_url":{"type":"string","format":"uri","description":"Direct URL to view this project in the Marcora app."},"visibility":{"type":"string","description":"Visibility (e.g. team, private)."},"status":{"type":"string","description":"Project status (e.g. active, archived)."},"content_count":{"type":"integer","description":"Number of content items in this project."},"created_by":{"type":"string","description":"Name of the project creator."},"member_count":{"type":"integer","description":"Number of project members."}},"required":["id","name","link_url"]}}
list_targeting_dimensions
Returns targeting dimensions and their options for the current team. Dimensions are categories (e.g. Buying Stage, Persona) with selectable options used to target content generation.
Pass dimension option IDs as dimension_option_ids when calling create_content to generate content targeted to specific audiences or stages.
---OUTPUT_SCHEMA---
{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Dimension ID."},"name":{"type":"string","description":"Dimension name (e.g. Buying Stage, Persona)."},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Option ID. Pass in dimension_option_ids when creating content."},"name":{"type":"string","description":"Option name (e.g. Awareness, Decision)."}},"required":["id","name"]}}},"required":["id","name","options"]}}
list_workflows
List workflows for the user's active team. Supports optional status filter and substring search.
Input roles:
- status: "draft" | "active" | "archived". Omit to return all.
- search: substring to match against workflow name.
- page / per_page: pagination. Default page=1, per_page=20, max per_page=100.
Usage patterns:
- Before create_workflow: call list_workflows with `search:` to check for duplicate-name workflows.
- When the user asks "what workflows do I have": call with no filters.
- When the user asks "what's my automation doing?": filter by status="active".
- Each item's `id` is a UUID string. Use it as `workflow_id` in get_workflow / update_workflow / run_workflow / get_workflow_runs.
---OUTPUT_SCHEMA---
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid"},
"name": {"type": "string"},
"status": {"type": "string"},
"link_url": {"type": "string", "format": "uri", "description": "Direct URL to view this workflow in Marcora."}
}
}
},
"itemsTotal": {"type": "integer"},
"curPage": {"type": "integer"},
"nextPage": {"type": ["integer", "null"]},
"prevPage": {"type": ["integer", "null"]}
}
}
run_workflow
Manually run a workflow. Creates a workflow_run and dispatches a Managed Agents session. Returns the run row — check .status to know what happened.
Input roles:
- workflow_id: UUID string of the workflow to run.
- input_values: object matching the workflow's declared inputs schema. Call get_workflow first if unsure.
Usage patterns:
- Always inspect the returned .status:
- "running" → dispatch succeeded; a real Managed Agents session is live.
- "failed" → dispatch failed; .error_reason has the cause. Tell the user specifically what went wrong.
- "skipped" → the runner decided no work was needed (rare for manual runs, common for scheduled).
- For scheduled runs, prefer creating a trigger via create_workflow's schedule_config — don't loop run_workflow calls.
- input_values must match workflow.inputs schema. For workflows with no declared inputs, pass {} or omit.
- The returned `id` is a UUID string for the workflow_run. Use it as `run_id` in get_workflow_runs (single-mode) to inspect the run.
---OUTPUT_SCHEMA---
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid", "description": "Workflow run UUID."},
"workflow_template_id": {"type": "string", "format": "uuid", "description": "Parent workflow UUID."},
"status": {"type": "string"},
"trigger_type": {"type": "string"},
"runner_session_id": {"type": "string"},
"error_reason": {"type": ["string", "null"]},
"error_summary": {"type": "string"},
"link_url": {"type": "string", "format": "uri", "description": "Direct URL to view this run in Marcora."}
}
}
update_brand_foundation
Overwrites one of the team's four Brand Foundation elements with new content. **Always full-replace — no patch semantics.**
**Before calling this tool, you should typically call `get_brand_foundation({elements: ["<element>"]})` first** to read the current value so the user can confirm what's being replaced. Brand Foundation content shapes every AI-generated piece of content the team produces, so unintended overwrites are costly.
**Elements and limits:**
- `company_overview` — general information about the company (max 10,000 chars)
- `brand_voice` — tone, core values, mission, personality (max 20,000 chars)
- `writing_style` — language complexity, sentence structure, formatting preferences, CTA style (max 20,000 chars)
- `writing_examples` — sample content demonstrating the team's distinctive voice (max 20,000 chars). Free-form — organize however the user likes.
Pass the new `content` as markdown. Existing content for the element is replaced in full. Other elements are untouched. If the team has no row for the element yet, one is created.
Returns the updated element name and content. To re-read the team's full Brand Foundation, call `get_brand_foundation`.
---OUTPUT_SCHEMA---
{"type":"object","properties":{"element":{"type":"string","enum":["company_overview","brand_voice","writing_style","writing_examples"],"description":"Which element was updated."},"content":{"type":"string","description":"Updated markdown content."}}}
update_content
Updates a content document (canvas or deliverable) identified by `content_id`. All update fields are optional — only the fields you supply are touched; everything else is left exactly as it was. At least one mutable field must be supplied (else error).
**Use this tool to:**
- Edit the markdown body (`content`)
- Override the auto-derived document name (`name_override`)
- Mark a doc ready or move it back to in-progress (`stage`)
- Share with team or make private (`visibility`)
- Categorize the document (`category_id`)
- Add/move the doc to a project (`project_id`)
**Reading before writing:** for `content` updates that splice into existing text, call `get_content` first, edit the markdown in your context, then send the FULL new body back. This tool replaces the entire body — there is no patch / diff mode.
**Name behavior:** by default a document's name auto-syncs from the first markdown header in its body. Set `name_override` to lock a custom name; once locked, the title stays even when the body is edited. Omit `name_override` to leave the lock state as-is. There is no un-lock path in this tool — once a name is custom, it stays that way.
**Stage:** `in_progress` or `ready`. Setting `stage` writes both the `stage` enum and the `is_ready` bool in lockstep. For deliverables linked to a content plan, transitioning to `ready` also moves the plan to Complete (side-effect, non-blocking on failure).
**Visibility:** `private` (only the creator and project members can see it) or `team` (anyone on the team). Downgrading `team → private` revokes team-wide access on the next read.
**Category:** `category_id` from `list_content_categories`. Works for BOTH canvas and deliverable documents. A category from another team errors.
**Project association:** pass `project_id` to set the document's single project association. If the document is already in a different project, the old association is replaced. If it's already in the supplied project, this is a no-op. To leave project association untouched, omit `project_id`. This tool does not provide a way to remove a doc from all projects — use the Marcora app for that.
**Authorization:** you must be a non-viewer member of the team that owns the document, AND either (a) you created the document, or (b) the document is team-visible. Foreign-team or insufficient-role calls return access denied.
**Errors:**
- `notfound` — `content_id` doesn't match any canvas or deliverable.
- `inputerror` — no mutable field supplied; invalid `category_id`; invalid `project_id`; document is a non-editable canvas type (e.g. context_item editor canvas).
- `accessdenied` — you don't have write access to the document.
---OUTPUT_SCHEMA---
{
"type": "object",
"properties": {
"content_id": {
"type": "string",
"format": "uuid",
"description": "Content identifier."
},
"name": {
"type": "string",
"description": "Document name (computed from name_override + has_custom_name + content header)."
},
"content": {
"type": "string",
"description": "Full document content in markdown."
},
"visibility": {
"type": "string",
"description": "Enum: private or team."
},
"stage": {
"type": "string",
"description": "Enum: in_progress or ready."
},
"category": {
"type": ["object", "null"],
"description": "Content category, or null if not categorized.",
"properties": {
"id": {
"type": "integer",
"description": "Category ID."
},
"name": {
"type": "string",
"description": "Category name."
}
}
},
"link_url": {
"type": "string",
"description": "Direct URL to view this content in Marcora."
}
},
"required": ["content_id", "name", "content"]
}
update_context
Use this tool to update an existing context item in your reference library.
Input semantics:
- context_item_id: REQUIRED. The UUID of the context item to update. Use list_context_items, list_context_collections, get_project, or get_relevant_context to find IDs.
- name: OPTIONAL. If provided, updates the name. Omit to leave unchanged.
- content: OPTIONAL. New markdown body. If provided, updates content and triggers RAG re-embedding. Omit to leave content unchanged. Mutually exclusive with content_url.
- content_url: OPTIONAL. Public URL the backend should fetch and convert to clean markdown server-side (same engine as the url_to_markdown tool — headless browser + Mozilla Readability). Use this instead of content when the new body is large or you'd otherwise have to web_browse/web_fetch the URL into your own context just to forward it. Mutually exclusive with content. Providing both → 400.
- collection_id: REQUIRED (but nullable). You MUST pass this every call. Pass the current collection ID to keep the item in its collection, pass a different ID to move it, or pass null to remove it from any collection.
- project_id: REQUIRED (but nullable). You MUST pass this every call. Pass the current project ID to keep the item associated with its project, pass a different ID to move it, or pass null to disassociate it from any project.
Important: collection_id and project_id use full-replace semantics. Omitting them is NOT the same as leaving them unchanged — you must always provide both (or null). If you do not know the current values, call get_context_item, get_relevant_context, or use the web app to check before updating.
If the context item has a linked canvas (for sidebar AI-assistant editing), its title, content, and word_count are automatically synced and a realtime update is broadcast to any open editors.
Authorization: same rules as add_context — you must be a member of the team that owns the item, private collections must be owned by you, and project-scoped updates require project membership for collaborators.
---OUTPUT_SCHEMA---
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Context item ID"
},
"name": {
"type": "string",
"description": "Updated context item name"
},
"content": {
"type": "string",
"description": "Updated reference content"
},
"content_intro": {
"type": "string",
"description": "Truncated content intro used in listings"
},
"collection_id": {
"type": ["integer", "null"],
"description": "Collection this item belongs to (null if none)"
},
"project_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Project this item is associated with (null if none)"
},
"word_count": {
"type": "integer",
"description": "Word count of updated content"
},
"updated_at": {
"type": "integer",
"description": "Unix timestamp of last update"
},
"relevancy_processed_status": {
"type": "string",
"enum": ["unprocessed", "provisional", "complete"],
"description": "RAG re-processing status. Set to 'unprocessed' whenever name or content changes."
},
"link_url": {
"type": "string",
"description": "URL to view this context item in the Marcora web app."
}
}
}
update_plan
Partial update of a plan. Only keys you send mutate — unspecified keys are preserved. Stage transitions enforced server-side per the state machine.
Call get_plan FIRST to see current state before constructing your update. Construct a minimal diff.
Input roles:
- plan_uuid: Required. The UUID from a prior create_plan or list_plans response.
- title / description / prompt: Update the human-facing or executable text.
- blueprint_id / project_id / category_id / due_date: Update executable parameters. Pass null to clear.
- assigned_to: Reassign to another team member (must be a current team member).
- reference_document_ids: REPLACES (not merges) the full set. Pass [] to clear all.
- context_collection_ids: REPLACES the full set. Pass [] to clear all.
- targeting_dimension_ids: REPLACES the full set. Pass [] to clear all.
- target_stage: Trigger a stage transition. Use UNDERSCORE form `In_Process`. Validated server-side — disallowed transitions return InputError with the disallowed pair.
Allowed transitions:
Suggested → Accepted (user accepts the suggestion)
Suggested → Dismissed (user rejects it)
Accepted → In_Process (content is being created — usually triggered automatically)
Accepted → Dismissed
In_Process → Complete (content reached ready — usually triggered automatically)
In_Process → Accepted (content was deleted — plan reverts)
In_Process → Dismissed
Complete → Accepted (Re-open the plan — clears produced_content_id and completed_at)
Complete → Dismissed
Dismissed → (nothing — terminal)
DO NOT send (server rejects with InputError "{field} is immutable" or "{field} is server-managed"):
- source, source_metadata, created_by, team_id, id, plan_uuid (as update value), produced_content_id, created_at, updated_at, completed_at, dismissed_at — all server-managed.
Usage patterns:
- **Dismiss a plan:** { plan_uuid: X, target_stage: "Dismissed" }
- **Re-open a Complete plan:** { plan_uuid: X, target_stage: "Accepted" } — confirm with user FIRST; this clears produced_content_id.
- **Reassign:** { plan_uuid: X, assigned_to: <user_id> }
- **Accept a Cora-suggested plan:** { plan_uuid: X, target_stage: "Accepted" }
Errors:
- NotFound — plan_uuid doesn't exist or is not visible to your team.
- InputError: stage transition {from} → {to} not allowed — target_stage violates the allowed-transition map.
- InputError: source is immutable / source_metadata is immutable — caller included an immutable field.
- InputError: assigned_to is not a member of the team — target user is not a current team member.
- AccessDenied — JWT doesn't resolve to the right team context.
---OUTPUT_SCHEMA---
{
"type": "object",
"required": ["plan_uuid", "stage", "updated_at"],
"properties": {
"plan_uuid": { "type": "string" },
"id": { "type": "integer" },
"team_id": { "type": "integer" },
"created_by": { "type": "integer" },
"assigned_to": { "type": "integer" },
"stage": { "type": "string", "enum": ["Suggested", "Accepted", "In_Process", "Complete", "Dismissed"] },
"source": { "type": "string" },
"source_metadata": { "type": ["object", "null"] },
"title": { "type": "string" },
"description": { "type": ["string", "null"] },
"due_date": { "type": ["string", "null"] },
"prompt": { "type": ["string", "null"] },
"blueprint_id": { "type": ["string", "null"] },
"project_id": { "type": ["string", "null"] },
"category_id": { "type": ["integer", "null"] },
"produced_content_id": { "type": ["string", "null"] },
"reference_documents": { "type": "array" },
"context_collections": { "type": "array" },
"targeting_dimensions": { "type": "array" },
"created_at": { "type": "integer" },
"updated_at": { "type": "integer" },
"completed_at": { "type": ["integer", "null"] },
"dismissed_at": { "type": ["integer", "null"] }
}
}
update_project
Use this tool to update mutable fields on an existing Marcora project.
To set or change the project's brief, pass an existing content UUID as `project_brief_id` - the tool resolves it to the appropriate document wrapper internally. **If the content isn't already attached to the project, this tool will attach it for you AND set it as the brief in one call** — you don't need to add the content separately first.
Important notes:
- Only fields you pass are updated (PATCH semantics). Omit a field to leave it unchanged.
- `visibility` must be exactly `team` or `private`.
- `status` must be exactly `active` or `archived`.
- `name` must be non-empty when provided.
Common use cases:
- "Set the brief on the Acme Launch project to <content>" -> call with project_id and project_brief_id (works whether or not the content is already in the project).
- "Rename the project" -> call with project_id and name.
- "Make the project private" -> call with project_id and visibility="private".
- "Archive the project" -> call with project_id and status="archived".
---OUTPUT_SCHEMA---
{"type":"object","properties":{"success":{"type":"boolean","description":"True if the update applied successfully."},"message":{"type":"string","description":"Human-readable status message."},"project":{"type":["object","null"],"description":"The updated project record."}},"required":["success"]}
update_workflow
Partial update of a workflow template. Only keys you send mutate — unspecified keys are preserved. Call get_workflow first to see the current state; then construct the minimal diff.
Input roles:
- workflow_id: UUID string of the workflow to update.
- name / description / steps / inputs / allowed_tools / tags: partial overrides.
- status: "draft" | "active" | "archived". Use "archived" as soft-delete.
Usage patterns:
- To activate: {workflow_id: "<uuid>", status: "active"}.
- To soft-delete: {workflow_id: "<uuid>", status: "archived"}.
- To rename: call get_workflow first, then send just {workflow_id, name}.
Do NOT send:
- schedule / schedule_config — rejected with InputError. Direct the user to the UI for schedule edits.
---OUTPUT_SCHEMA---
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid"},
"name": {"type": "string"},
"status": {"type": "string"},
"steps": {"type": "array"},
"inputs": {"type": "object"},
"allowed_tools": {"type": "array"},
"tags": {"type": "array"},
"updated_at": {"type": "integer"},
"link_url": {"type": "string", "format": "uri", "description": "Direct URL to view this workflow in Marcora."}
}
}