Marcora

Creates a content plan (a planned piece of content: what to write and with which inputs) for the user's active team. It does not write the content: use `produce_plan` to generate a plan's content, or `create_content` to write something now. `title` is the only required field. Before you create: - **Dedupe:** call `list_plans` with a `project_id` filter before creating plans for a project. If a matching plan exists in Accepted or Suggested, offer to update it (`update_plan`) instead. - **Source:** "cora_requested" (default) when the user explicitly asked; "cora_proactive" for an unprompted suggestion. Never use "workflow" or "playbook" from an interactive session. What the server decides: - **Starting stage is automatic from `source`:** cora_requested / playbook → Accepted (actionable now); user_added / cora_proactive / workflow → Suggested (needs the user to accept before it can be produced). - **Visibility:** "private" (default; the creator's ideas queue, invisible to teammates) or "team". Passing `assigned_to` for anyone other than the caller auto-promotes the plan to "team", even over an explicit "private". - `assigned_to` must be the NUMERIC user id of a current team member; emails and names are rejected. - `source_metadata` is immutable after creation. Useful inputs: `prompt` (the actual content prompt used when the plan is produced), `due_date` (YYYY-MM-DD), `blueprint_id` (UUID from `list_blueprints`, or integer id), `project_id`, `category_id`, `reference_document_ids`, `context_collection_ids`, `targeting_dimension_ids`. When creating several plans in one turn, set `source_metadata.batch_id` (a client-generated UUID) to correlate them, then link the user to the filtered plans view for that batch. Present `link_url` exactly as returned. **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: blueprint UUID (from list_blueprints) or integer blueprint id. UUIDs are resolved to the internal id server-side; an unknown UUID returns InputError naming list_blueprints. - 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" | "cora_proactive" | "user_added" | "workflow" | "playbook". - 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}. - assigned_to: optional NUMERIC user id. Defaults to the calling user. - visibility: "private" (default) | "team". Assignment is a communication act, hence the auto-promotion. - plan_uuid: optional client-supplied UUIDv4 for optimistic creates. The server validates format and uniqueness and rejects collisions with InputError; it generates one if omitted. **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 (omitted or empty). - InputError: source must be one of [user_added, cora_proactive, cora_requested, workflow, playbook]. - InputError: plan_uuid already exists (a client-supplied UUID collides with an existing plan in this team). - InputError: invalid plan_uuid format (not a valid UUIDv4). - InputError: assigned_to is not a member of the team. - InputError: assigned_to must be the numeric user id of a team member (a non-numeric value was sent). - InputError: visibility must be one of [private, team]. - AccessDenied: JWT does not resolve to a valid team context. **Links:** copy `link_url` character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

create_plan

Create a reusable content playbook — an ordered template of content-plan items ("save a repeatable content sequence"). Provide a name and, optionally, the ordered items; each item becomes one content plan when the playbook is instantiated. Visibility: defaults to "team" (visible to all active teammates). Pass visibility "private" to keep it creator-only. Anchor date: if the user is building this playbook around a specific real date (a launch, an event, a campaign kickoff), offer to set `anchor_date` — it's the reference point every item's `offset_days` counts from, and it becomes the default when they instantiate. It's optional; leave it off for an evergreen/undated template. The response includes `link_url` — share it so the user can open the playbook you just created. When to use: when the user wants to author or save a reusable template/playbook of content plans from scratch (e.g. "make me a launch-week playbook", "save this sequence as a template"). To build a playbook from plans the user already ran, use create_playbook_from_plans instead. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

create_playbook

Create a playbook by capturing existing content plans as reusable template items ("save what worked as a template"). Pass the plan UUIDs; their title / description / prompt / blueprint / category are copied into ordered playbook items. Visibility: defaults to "team" (visible to all active teammates). Pass visibility "private" to keep it creator-only. When to use: when the user liked a batch of plans they already produced and wants to reuse that sequence later (e.g. "turn these plans into a playbook", "save this campaign as a template"). To author a playbook from scratch, use create_playbook. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

create_playbook_from_plans

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 create a project brief at the same time — two ways: - `project_brief_content`: supply the FINISHED brief text directly. It is saved as the project brief document as-is. NO Studio Credits used. - `project_brief_instructions`: supply a PROMPT describing the brief; the AI generates the brief document for you. Uses Studio Credits (charged when the brief completes, at the model's cost: 1 credit = 5¢, rounded up; typically 1-2) — if the team is out of credits this returns an `insufficient_credits` error (code 402) and the project is NOT created; pass `project_brief_content` instead. If both are supplied, `project_brief_content` wins (no AI). When a brief is created, the response includes a `project_brief` object containing the brief's `content_id` — use that with `update_content` / `get_content` later. 4) Use the returned `project_id` with `create_content` to associate new content with this project. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

create_project

*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. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

finalize_blueprint_draft

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.

get_blueprint

Returns the team's Brand Foundation: the foundational brand and company information that guides all AI-generated content. Read-only. Four elements: - **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 showing the team's distinctive voice (free-form; users organize it however they like) When to use: whenever the user asks about, or wants you to use, their brand voice, company overview, writing style or writing examples. For example: - "What is our brand voice?" / "What is the brand voice of <company>?" - "Summarize our company overview" - "What's our writing style?" / "Show me our writing examples" These four elements live ONLY here. `get_relevant_context`'s relevancy search does not return them, so don't reconstruct the answer from it or from web pages. (`get_relevant_context` with `include_brand_foundation: true` bundles them with relevant context when you are writing.) Returns all four elements by default; pass `elements` to scope the response to a subset. An element the team has not filled out yet comes back as an empty string. When you write content yourself, `get_relevant_context` with `include_brand_foundation: true` returns Brand Foundation together with relevant context in one call. You don't need to call this before `create_content` with `instructions` or before `create_plan`: those pull Brand Foundation in automatically. To change an element, use `update_brand_foundation`. Present `link_url` (it opens the Brand Foundation section in the Marcora web app) exactly as returned. The response is structured JSON: paste it directly into a downstream AI prompt, or template the fields into markdown. Copy `link_url` character for character; never retype, shorten, or rebuild a link or the IDs inside it.

get_brand_foundation

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.

get_community_blueprint_details

Retrieves the full markdown body of a specific content document by its content_id (UUID). **Always warranted: reading a project's BRIEF.** When `get_project` or `get_relevant_context` returns a `project_brief` block with `truncated: true`, call this tool with that `content_id` before drafting, revising, assessing or critiquing anything in that project. The brief states the premise and the structural decisions already taken, and work produced without it is likely to contradict them. The caution below does not apply to it. **Otherwise, 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. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_content

Fetch one Context Intelligence finding in full detail by its UUID (from list_context_intelligence_findings). When to use: the user wants the specifics of a finding — the full recommendation, the suggested fix content, or which context items it involves — before deciding to act on it. The suggested_fix object (when present) contains the proposed replacement content; applying it is done in the Marcora web app (or via update_context_intelligence_finding_status to acknowledge/dismiss/resolve without applying). **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_context_intelligence_finding

Opens a single context item by ID and returns its full markdown content and metadata. Use it when you already have an item's ID and need to read the whole item — list_context_items returns only content_intro (a short truncation), and get_relevant_context returns matched passages. The ID can come from list_context_items, get_project(project_id).context_items, or the `sources` of get_relevant_context. It does not search; to find material relevant to a question, use get_relevant_context. 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. For web-page items (content_type "webpage"), source_url is the page's tracked URL — pass it back to add_context connected_webpage_url, or call update_context refresh_webpage to re-pull it. It is null for non-webpage items. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_context_item

Returns profile and subscription information for the currently authenticated user. Use this to personalize responses, check the user's active team, or confirm subscription limits before creating content. Key fields: - active_team_name / active_team_role: current working team context - subscription_status + plan_name: confirms what features are available - ai_credits_available / ai_credits_max: Studio Credits remaining and the plan's limit for the current billing period

get_current_user_info

Checks the status of an async generation by `generation_id`. Read-only. These flows return a `generation_id` you can poll here: - `create_content` with a `blueprint_uuid` or `generation_mode: "multi_model"` (document generation), and `produce_plan`; - `ask_content_assistant` (the in-document Content Assistant); - `apply_grounding_fix` (each job in `jobs[]`; jobs whose fixes land in the same document share one `generation_id`, so poll each distinct id once). The response always includes `status`, `generation_id` and `flow_type`, plus `generation_mode` ("quick" or "multi_model") when known. `content` is null until the run finishes: keep polling. **Document generation** (`flow_type` != "ai_assistant"): finishes at status `"completed"`. `content` = { content_id, name, link_url } (plus `blueprint_id` with a blueprint). Give `link_url` to the user to review in Marcora; you don't need `get_content` unless they later ask about the body. **Content Assistant flow** (`flow_type` == "ai_assistant", also used by `apply_grounding_fix`): finishes at status `"complete"`. `content` = { content_id, name, link_url, assistant_summary, document_updated, current_content }. `document_updated` says whether the turn this run produced changed the document body (false for a reply-only run, or a grounding fix that was already covered). `status` tracks THIS run; `content` is the document's LIVE current state (including the user's own later edits), while `assistant_summary` and `document_updated` describe the turn this run produced. Statuses: pending, processing, streaming, complete (Content Assistant) / completed (blueprint), failed. Present `link_url` exactly as returned. **Content fields:** - `assistant_summary`: the assistant reply this run produced, as the sidebar thread shows it. Null if the run has written no reply, or it was written before runs were tracked; a reply that used sources you cannot open comes back as a notice. - `document_updated`: whether the turn this run produced changed the document body. For a shared `generation_id` from `apply_grounding_fix`, it covers every finding in that run. - `current_content`: the document's current markdown. Returning the live document is deliberate: a stale snapshot isn't useful, the current version is. When the user has the document open in Marcora, the reply and any edits already streamed in live via the realtime channel; polling here is for headless callers, or to retrieve the current document and this run's reply text. **Links:** copy `link_url` character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_generation_status

Read the result of a content grounding scan started by check_content_grounding — the poll companion to it. When to use: check_content_grounding returned status="running" (its ~20s inline wait elapsed before the scan finished). Poll this with the **scan_id** it gave you, roughly every 15-30 seconds; a fresh scan usually completes within 120-150 seconds. Do NOT call check_content_grounding again — that starts a second scan and charges again. Which id to pass: - `scan_id` — reads that exact scan. This is what you want when polling: it always reports the run you started, whatever its status. - `content_id` (no scan_id) — reads the latest COMPLETED grounding for that document. Use it to ask "what is this document's grounding state right now" without starting a scan. It deliberately skips a scan that is still running, so it is NOT the right call for polling — you would get the previous result back marked complete. It never starts a scan and never charges credits — it returns immediately with whatever the current state is. The response envelope is identical to check_content_grounding's, so the same handling works for both. Errors: - Provide 'scan_id' or 'content_id' (400) — one of them is required. - Not a valid UUID (400) — malformed scan_id or content_id. - Scan not found (404) — no such grounding scan in your team. - Content not found (404) — no such content in your team. - scan_id and content_id refer to different content (400) — pass scan_id alone. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_grounding_result

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 you. Cross-team plans return NotFound, not AccessDenied. A teammate's PRIVATE plan (visibility='private', you are neither creator nor assignee) also returns NotFound — do not retry. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_plan

Fetch one content playbook by id, including its full ordered list of items. When to use: to inspect a playbook before instantiating or editing it, or when the user asks about the contents of a specific saved playbook/template. NotFound also covers a teammate's PRIVATE playbook (visibility='private', caller is not the creator) — do not retry. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_playbook

Returns details for a specific project: its members, documents, context items, and — when one is set — the project's **brief**. **Read the brief before doing substantive work in this project.** The `project_brief` block is the project's authoritative statement of premise, scope and the structural decisions already taken. Its `content_intro` is an excerpt (the full body when the brief is short, otherwise the opening ~400 words with `truncated: true`); call `get_content` with its `content_id` for the full text. The other documents and context items in this project may be older than the brief, or may contradict it — the brief wins. Work produced without reading it is likely to contradict decisions already made. The matching entry in `documents` is flagged `is_project_brief: true` and sorted first. Use `list_projects` to discover available projects and find the `project_id`. `project_brief.content_id` also doubles as the shortcut for EDITING the brief via `update_content`.

get_project

Searches the team's Marcora context library and returns up to 10 passages most relevant to a prompt, plus `sources` (each with a `link_url`) for citing. Read-only. When to use: - The user wants writing grounded in their team's brand or company context (a blog post, email, social post, landing page, press release, ad or messaging): call this with `include_brand_foundation: true` and write it yourself from what it returns. If asked to save it, use `create_content` `content`. - The user asks about their own company, product, positioning, launches or competitors ("what do we have on competitor X?"): call it and answer from their context. - Before saving text you wrote yourself through `create_content` / `update_content` `content`: those store it verbatim and consult no context. When NOT to use: - Before `create_content` with `instructions` (the Marcora-writes path): Marcora gathers the context itself. - For brand voice, company overview, writing style or writing examples on their own: relevancy search never returns Brand Foundation. Use `get_brand_foundation`, or set `include_brand_foundation: true` here. Inputs: - `prompt` (required): what you need; specific prompts return better chunks. - `include_brand_foundation`: true on the FIRST call of a conversation (adds company overview, brand voice, writing style and writing examples); false or omitted afterwards. - `project_id`: adds that project's items and, on the first call, returns its `project_brief`. Read the brief before drafting: it outranks older chunks. Set `include_project_brief: false` on later calls for the same project. - `collection_ids` and `project_id` broaden the search (additive, never an exclusive filter); `dimension_option_ids` biases toward an audience, persona or industry; `context_rag_ids` excludes chunks already returned when you page for more. Present each `link_url` exactly as returned. **How results are ranked:** each passage is scored on its own and against the whole document it belongs to, and the two scores are blended; weak matches are dropped, so fewer than 10 can come back. `dimension_option_ids` lean the ranking toward the chosen audience, persona or industry. It searches the reference library plus the project, collections and shared collections the user can access. **Sources:** each `sources` entry carries the item name, content_type, a `link_url` deep-link that opens the item in the Marcora web app (plus `source_url`, the original external page URL, for webpage items), its collection_id / project_id / last_updated, and the `context_rag_ids` from that item. Use these to cite or link the material you surface. (The previous top-level `context_item_ids` field has been replaced by `sources`; each source's `context_item_id` gives you the same IDs.) **Project brief:** with `project_id`, the response carries a top-level `project_brief` block: the project's authoritative statement of premise, scope and the structural decisions already taken. It is the same block `get_project` returns (`content_id`, `name`, `word_count`, `content_intro`, `truncated`, `read_first`). Read it before drafting, revising, assessing or critiquing anything in the project; context chunks may be older than the brief or contradict it, and the brief wins. When `truncated` is true, `content_intro` is only the opening excerpt, so call `get_content` with its `content_id` for the full text. The brief is stored as content, not as a context item, so relevancy search never surfaces it: this block is the only way it reaches you from this tool. The key is absent when the project has no brief. `include_project_brief` defaults to true and is ignored without `project_id`. **Brand Foundation bundling:** `include_brand_foundation: true` returns the team's Brand Foundation (company overview, brand voice, writing style, writing examples) in the same response. It is the always-on foundational context relevancy scoring never surfaces on its own. Pull it once, up front, so you have it for the rest of the session; you don't need it when handing off to `create_content` with `instructions`, which pulls it in automatically. **Errors when you pass `project_id`:** "Project not found" means the project doesn't exist or belongs to a team other than your active team (check `list_projects`, or `set_active_team` if it is in another team). "You are not a member of project <id>" means the project is private and you are not a member: ask a member to add you, or search without `project_id`. Neither error returns any context or brief. **Links:** copy `link_url` character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

get_relevant_context

ALWAYS use this when the user asks what team accounts they have, which teams they belong to / are on, or wants to switch teams — do NOT answer from memory or session context, which knows ONLY the single currently-active team and will undercount (a user can belong to many teams). This tool is the only way to enumerate the full list. Returns every team you belong to, each with its full member roster. Read-only. Also use this BEFORE assigning a plan or content to a teammate (to look up their numeric user_id — the value `update_plan.assigned_to` / `create_plan.assigned_to` expect), or to answer questions about the team's members and your role. Each team includes: team_id, team_name, is_active (exactly one team is your active team — see set_active_team to change it), your_role, and members[]. Each member has: user_id (the numeric id assignment expects; null for a pending invite that hasn't been accepted), name, email, role, and status ("active" or "invited"). Deliberately does NOT include credits or subscription info — call get_current_user_info for those.

get_team_info

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.

import_community_blueprint

Run a playbook: create one content plan per playbook item, in order, as a batch. Plans land in the Accepted stage with source "playbook" and INHERIT the playbook's visibility (team playbook → team plans; private playbook → private plans). Optionally anchor due dates to a date (each item's offset_days is applied to anchor_date; defaults to the playbook's saved anchor_date if it has one) and/or scope the batch to a project. The response groups the plans under a new CYCLE — use `run.link_url` to hand the user "here's your cycle" and each plan's `link_url` for the individual pieces. When to use: when the user wants to actually deploy / kick off / run a saved playbook into real content plans (e.g. "run my launch playbook", "instantiate this template anchored to next Monday"). This is a distinct bulk action — it does NOT create or edit the playbook itself. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

instantiate_playbook

Invite someone to your Marcora account by email. An invitation email is sent automatically, and the response also returns the exact invite link (invite_link) so you can share it directly — e.g. paste it to the person in Slack. Roles: - "creator" — a full team member who can create and edit content. - "admin" — a team administrator. - "collaborator" — a project-scoped collaborator who only works inside a specific project. Who can invite whom: - You must be an ADMIN to invite someone as an "admin" or a "creator". Admins can invite any role. - A "creator" can invite "collaborator"s only. - Viewers cannot invite anyone. project_id (a project UUID from list_projects): - REQUIRED when role is "collaborator" — it is the project they will collaborate on. - OPTIONAL for "creator" and "admin". It does NOT limit their access (creators and admins keep full team access); it simply also adds them to that project and makes their invite link drop them straight into it on first sign-in. The invitee is emailed automatically: brand-new users get a sign-up link (returned in invite_link); existing users who still belong to an active team get a login link and will see the invitation in-app after they log in; existing users with no active team (e.g. a removed teammate) get a sign-up link to rejoin with their existing password. The call fails if the email is already an active team member (with no project to add them to), already has a pending invitation, or if you lack permission for the requested role.

invite_user

Returns Marcora's guide to its own tools: what each Marcora object is, which tool fits which request, the order the tools chain in, and the mistakes to avoid. **When to use this tool:** call it once before multi-step Marcora work the user has asked for — for example generating content into a project, setting a project brief, adding reference context, or producing a content plan — or whenever you are unsure which Marcora tool fits a request or how two of them chain. If the Marcora skill is already loaded in your context, you don't need this tool: it holds the same guidance. Called with no `topic`, it returns an overview (the object model, the context model, a which-tool table) and the list of topics, each with a one-line summary. Call it again with `topic` for the one section the task needs; don't fetch every topic. Read-only: it reads no workspace data, changes nothing, and uses no credits.

learn_marcora_tools

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.

list_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.

list_community_blueprints

Lists the team's content (documents the team has created, from scratch or from blueprints) that the current user can see, as a single unified array with consistent field names, newest first. Use it to browse and filter the team's content and to find content IDs. Use content_id with get_content to retrieve a piece in full. Use create_external_share to share content externally. **Optional `search`:** pass a natural-language query to sort the list by similarity to it instead of recency. Each row then carries a relevance_score (cosine 0–1, higher = more similar). Search only re-orders: every visible row is still returned, with no cutoff, so the response is as large as the team's content. Scores are comparable with list_context_items. To find passages in the reference library that are relevant to a question, use get_relevant_context.

list_content

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).

list_content_categories

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. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

list_context_collections

List Context Intelligence findings for the team — issues Marcora's automated scans detected in the team's reference/context library (stale content, contradictions, outdated web sources, classification gaps). When to use: the user asks about their context health, what Context Intelligence found, open findings, or what needs attention in their reference library. Also the right first call before updating any finding's status. Findings are returned newest-first. Each has a status lifecycle: pending (new, needs review) → acknowledged / dismissed / resolved. Filters (all optional): - status: "pending" | "acknowledged" | "dismissed" | "resolved". Use "pending" for the actionable queue. - severity: finding severity as recorded by the scan (e.g. "high", "medium", "low"). - process_type: which scan produced it — "health_audit" (library-wide sweep) | "web_freshness" (tracked webpage changes). - page / per_page: pagination. Default per_page=20, max=100. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

list_context_intelligence_findings

Lists the context items in the team's reference library, newest first. Use it to browse and filter the library and to find context-item IDs. 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), a short content_intro, and a link_url that opens it directly in the Marcora web app. To get the full markdown content of an item, pass its id to get_context_item. For web-page items (content_type "webpage"), source_url is the page's tracked URL — useful for spotting which items can be refreshed (update_context refresh_webpage). It is null for non-webpage items. **Optional `search`:** pass a natural-language query to sort the list by similarity instead of recency. Each item is scored by its best-matching passage and carries a relevance_score (cosine 0–1, higher = more similar); items with no indexed passages yet have a null score and sort last. Search only re-orders: every item you can see is still returned, with no cutoff, so the response is as large as the library. To find the passages that are relevant to a question, use get_relevant_context, which returns the top passages with their sources. 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 a sources array with the parent context items of matched passages. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

list_context_items

Lists content plans for the user's active team as paginated summary rows; use `get_plan` for full detail. Read-only. Use it to find plans to act on and to dedupe before `create_plan`. Results are visibility-scoped: team-visible plans plus the caller's own private plans (as creator or assignee). A teammate's private plans never appear, so an empty result does not mean the team has no plans. Filters: - `stage`: array of Suggested, Accepted, In_Process (underscore form), Complete, Dismissed. Omit for all stages. - `source`: array of user_added, cora_proactive, cora_requested, workflow, playbook. - `project_id` (project UUID), `category_id` (integer). - `assignee_scope`: "me" (default) | "created_by_me" | "all_visible" (team-visible plus your own private ones). - `sort`: "due_asc_nulls_last" (default) | "created_desc". - `page` / `per_page`: default 20, max 100. ⚠️ Known limitations (accepted but not applied yet): `due_before`, `due_after` and `search_text` do not filter; for multi-value `stage` / `source` arrays only the FIRST element is honored, so pass single-value arrays. Common uses: - **Dedupe before create:** filter by `project_id`; if a matching plan is Accepted or Suggested, offer to update it instead of creating a duplicate. - **Workflow suggestions awaiting review:** `source=["workflow"]` + `stage=["Suggested"]`. - **Plans I created:** `assignee_scope="created_by_me"`. Present `link_url` exactly as returned. **Upcoming week view (once the date filters apply):** due_before = (today + 7 days, YYYY-MM-DD), sort = "due_asc_nulls_last". `due_before` / `due_after` take ISO date strings (YYYY-MM-DD). **Links:** copy `link_url` character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

list_plans

List all content playbooks visible to the caller in the current team: team-visible playbooks plus the caller's own private ones (a teammate's private playbooks never appear). Playbooks are reusable, ordered templates of content-plan items. When to use: whenever the user wants to see, pick from, or manage their saved playbooks / templates (e.g. "what playbooks do I have", "show my templates"), and before instantiate_playbook / update_playbook to find the right id. Returns summaries only — call get_playbook for a playbook's items. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

list_playbooks

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. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

list_projects

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.

list_targeting_dimensions

Produces (generates) the content a plan describes: the MCP equivalent of the plans board's Generate button. It writes a new document, saved to the user's Marcora workspace and linked to the plan. When to use: the user asks to generate, produce or create the content for an existing plan ("produce that plan"). To create a NEW plan use `create_plan`; to edit plan fields use `update_plan`. ⚠️ **Credits and duration:** it uses team Studio Credits (charged at completion, cost-based: typically Quick 1-2, Multi-model 6-7) and takes 1-5 minutes. Too few credits (Quick needs 1, Multi-model 5) fails with `insufficient_credits` (402), nothing generated. Confirm with the user before producing a plan they didn't explicitly ask to produce. **Mode (optional, omit for defaults):** `generation_mode` "quick" (one model) or "multi_model" (two drafts plus a synthesis); default Multi-model with a blueprint, Quick without. Quick only: `ai_provider` ("anthropic" default, "openai") and `use_extended_thinking` (default true; slower, costlier); ignored with Multi-model. **Requirements:** the plan must be "Accepted". A Suggested plan needs `update_plan` { target_stage: "Accepted" } first; In_Process / Complete plans already have content (`produced_content_id`). The plan's prompt, targeting dimensions, context collections and project are used automatically, so set them with `update_plan` BEFORE producing. **Asynchronous on both paths**, chosen from the plan: it returns at once with `path` ("blueprint" or "freeform") and a `generation_id`. Poll `get_generation_status`. On completion the plan moves to In_Process (`produced_content_id` set); the content reaching ready moves it to Complete. Errors: Missing param: plan_uuid; NotFound; InputError: plan is in stage {stage}; invalid mode, provider or thinking value. Present `link_url` exactly as returned; never retype, shorten, or rebuild a link.

produce_plan

Set your active team — the team all subsequent Marcora tool calls operate against. Input: team_id (the numeric id from get_team_info). ⚠️ GLOBAL EFFECT: switching your active team changes it EVERYWHERE for your account — open Marcora app tabs, any running Marcora sessions, and every other connected MCP client — because it writes the same active-team setting the in-app team switcher uses. Tell the user before you switch, and do NOT switch while other work is mid-flight for them. The response includes previous_team_id so you can restore their original team when you're done: switch → do the work → set_active_team back to previous_team_id. Rejects a team you don't belong to with a readable error (use get_team_info to see your teams).

set_active_team

Start a Context Intelligence health audit — a library-wide AI sweep of the team's context/reference items that produces findings (stale content, contradictions, gaps) reviewable via list_context_intelligence_findings. When to use: the user explicitly asks to check/audit their context health ("run a health check on our context", "scan the library"). Do NOT trigger one unprompted — always confirm first. ⚠️ Cost + gating: the scan consumes team Studio Credits and is gated — it requires the Command plan (active subscription) with at least 50 credits remaining, only one health audit can run at a time, and a cooldown applies after each completed run (the error message tells you when it can run again). Starting a new audit CLEARS the previous health-audit findings. The scan runs in the background; the response returns immediately with a scan_run_id. Findings land as the scan progresses — check list_context_intelligence_findings afterwards. Errors: - ci_not_eligible (403) — plan/subscription/credits gate failed (JSON error body with reason + credit numbers). - A health check is already running. Please wait for it to finish. - Health check ran recently. You can run it again in about {time}.

trigger_health_audit_scan

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, plus a `link_url` that opens the Brand Foundation section in the Marcora web app. When you point the user at their updated Brand Foundation, use that `link_url` exactly as returned — do not construct a Brand Foundation URL yourself; a hand-built one will 404. To re-read the team's full Brand Foundation, call `get_brand_foundation`. **Links:** present `link_url` to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

update_brand_foundation

Updates an existing content document (by `content_id`) in place. Use it to revise a document rather than creating a new one; Marcora keeps a full version history and the user can revert any change from the app. Only the fields you supply change, and at least one must be supplied. Fields: `content` (markdown body), `name_override`, `stage`, `visibility`, `category_id`, `project_id`, plus `change_summary`. **`content` REPLACES the entire body verbatim** (there is no patch mode), and this tool consults no Brand Foundation or Reference Library. So when you write or rewrite the body: call `get_content` to read the current body AND `get_relevant_context` with `include_brand_foundation: true`, then send the FULL new body. Skip both when you only change non-body fields. Side effects to know: - `stage: "ready"` on a document linked to a plan also moves the plan to Complete. - `name_override` locks a custom name permanently; this tool cannot unlock it. Without it, the name follows the first heading. - `project_id` replaces the document's single project association (no way to remove it from all projects here). - `visibility` "team" → "private" revokes team-wide access on the next read. **Pass `change_summary` on every call**: what you changed and why, as skimmable markdown (one line for a small edit; a short bulleted list for several). It is shown in the document's history sidebar. Needs write access: a non-viewer team member who created the document, or the document is team-visible. Present `link_url` exactly as returned. **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. **Stage:** `in_progress` or `ready`. Setting `stage` writes both the `stage` enum and the `is_ready` bool in lockstep. The plan side effect on `ready` is non-blocking on failure. **Visibility:** `private` (only the creator and project members can see it) or `team` (anyone on the team). **Category:** `category_id` from `list_content_categories`. Works for all content documents. A category from another team errors. **Project association:** if the document is already in a different project, the old association is replaced; if it is already in the supplied project, this is a no-op. Omit `project_id` to leave the association untouched. Use the Marcora app to remove a document from all projects. **Change summary format:** a single line for one small edit (e.g. "Tightened the closing CTA"); for several distinct edits, a short **bulleted list** where each bullet is a bold 2–5 word lead, a colon, then the detail. Match length to substance. Blank/omitted logs a generic "Content updated via MCP." and the history becomes useless after a few edits. **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 content document. - `inputerror`: no mutable field supplied; invalid `category_id`; invalid `project_id`; the document is a non-editable document type (e.g. a context-item editor document). - `accessdenied`: you don't have write access to the document. **Links:** copy `link_url` character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

update_content

Updates an existing context item in the team's reference library: rename it, replace its body, re-pull a tracked web page, or move it between collections and projects. Project and collection placement are independent: an item can sit in a project AND a collection at once. Moving an item into a collection changes `collection_id` only. - `collection_id` is REQUIRED (the key must be present; omitting it is a 400). Pass the current id to keep the item in its collection, a different id to move it, or null (or 0) to move it to the loose reference library. - `project_id`: omit it to leave the item's project exactly as it is. Pass a project id to move it to that project. Pass null ONLY when the user asked to take the item out of its project. Body and name (patch-style; omit to leave alone): - `name`: new name. - `content`: new markdown body; triggers re-embedding. - `import_url`: a public URL fetched once and converted to markdown server-side, replacing the body with a one-off snapshot. Use it instead of `content` for a large new body. `content` and `import_url` are mutually exclusive. `refresh_webpage: true` re-pulls a tracked web page from its stored URL (the app's refresh button). Valid only for items added with `add_context` `connected_webpage_url` (content_type "webpage"); requires admin or editor role. On that branch `name` / `content` / `import_url` are ignored, `collection_id` is not required, and the item's project and collection stay exactly as they were. Find ids with `list_context_items`, `list_context_collections`, `get_project` or `get_relevant_context`. Present `link_url` exactly as returned. **Input semantics:** - context_item_id: REQUIRED. The UUID of the context item to update. - refresh_webpage: OPTIONAL boolean. On any item other than a "webpage" item it returns a clear error. - name: OPTIONAL. Ignored when refresh_webpage is true. - content: OPTIONAL. Ignored when refresh_webpage is true. - import_url: OPTIONAL. Uses AI main-content extraction (the same engine as connected_webpage_url: it isolates the primary page/article body and drops nav and boilerplate). It is a one-off snapshot; to keep a web-page item in sync with its URL, use refresh_webpage instead. Ignored when refresh_webpage is true. - collection_id: REQUIRED (its value may be null). - project_id: OPTIONAL. Omit to leave the project unchanged; a project id moves the item there; null detaches it (only when the user asked). If the context item has a linked editor document, its title, content and word_count are auto-synced and a realtime update is broadcast to open editors. **Links:** copy `link_url` character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

update_context