create_content

Use this tool to save a new piece of content as a document in the user's Marcora workspace. By default you write the content yourself and save it with content: call get_relevant_context with include_brand_foundation: true, write the piece from what it returns, then save it. If the user wants a draft in the chat instead, don't call this tool. Marcora's own writer (instructions, optionally with blueprint_uuid) is for three cases only: the user asks Marcora to write it, a blueprint is used, or a plan is being fulfilled.

Document title — there is no title parameter. A document's title is always taken from its first heading, and it keeps following that heading when the document is edited later. So put the title IN the document:

• With content: start the markdown with the title as a level-1 heading on the first line — # <Title> — then the body.
• With instructions: if the user wants a specific title, say so in the instructions text (e.g. "Title it: Weekly Trends – Sept 16"). Marcora writes it as the document's first heading.
• Never pass both content and instructions — not even to carry a title. Pick one path; a call with both is rejected.

Revising an existing document? Use update_content instead — edit it in place rather than forking a new doc. Edits are non-destructive: Marcora keeps a version history and the user can revert from the app.

Context handling depends on which input you use. With content (you write it, the default for new content), the tool stores your markdown verbatim and consults no context. So call get_relevant_context with include_brand_foundation: true first (add project_id when writing for a project) and write from what it returns, otherwise your draft ignores the team's brand and reference material. With instructions (Marcora writes it: only when the user asks Marcora to write it, a blueprint is used, or a plan is being fulfilled), the tool pulls all relevant context internally — Brand Foundation + Reference Library (relevancy-scored) + Project Context (if project_id) + any collection_ids — so on that path do not pre-fetch with get_relevant_context; that's wasted work. To build on existing documents when you write it yourself, read them with get_content and write from them; reference_content_ids is for the instructions paths and is rejected with content.

Referencing existing content — use reference_content_ids: to have Marcora generate WITH REFERENCE to existing documents (a past post to echo, a brief to build on), pass their content UUIDs (from list_content, or list_content with search) in reference_content_ids. The tool resolves each id server-side, pulls its full text, and folds it into the generation prompt as reference material. THIS is the canonical way to include existing content — you no longer need to paste document text into instructions. Valid only on the generation paths (instructions, with or without blueprint_uuid); it is REJECTED with the verbatim content path, which consults no context. Unknown or inaccessible ids fail loud (the whole call errors), so pass ids you got from a list/get tool.

Choosing a path for net-new content: by default, write it yourself and save it with content, after grounding yourself with get_relevant_context (see above). Use instructions only when the user asks Marcora to write it, a blueprint is used, or a plan is being fulfilled. Saving content uses no Studio Credits.

With content (synchronous):
Creates a document with your supplied markdown-formatted content directly — no AI generation. SYNCHRONOUS — returns the content object immediately.

With instructions (no blueprint_uuid, Quick — synchronous):
Marcora writes a freeform document with one model. SYNCHRONOUS — takes about 45 seconds to 3½ minutes (allow a long timeout). Returns the content object directly.

With instructions + generation_mode "multi_model" (no blueprint_uuid, asynchronous):
Marcora writes two drafts and a synthesis. ASYNC — returns a generation_id immediately. Poll get_generation_status with the generation_id until the status is "completed". This takes 3-5 minutes.

With instructions + blueprint_uuid (asynchronous):
Generates content from a blueprint template. ASYNC — returns a generation_id immediately. You must then poll get_generation_status with the generation_id until the status is "completed". This typically takes 3-5 minutes and runs Multi-model by default.

Generation modes: pass generation_mode to choose how Marcora writes: quick (one model) or multi_model (two drafts and a synthesis). When you omit it, a call with a blueprint runs Multi-model and a call without one runs Quick. For Quick only, ai_provider picks which model family writes the document (the allowed values and the default are in the tool's input schema) and use_extended_thinking (default true) turns extended thinking on or off — slower and can use more Studio Credits when on; pass false for a faster run. Provider and thinking are ignored with Multi-model. All three apply to the instructions paths only.

Studio Credits: the instructions paths use Studio Credits, charged when the document completes at the model's cost (1 credit = 5¢, rounded up; typically Quick 1-2, Multi-model 6-7). Starting needs 1 credit available for Quick and 5 for Multi-model; otherwise the call fails with an insufficient_credits error (code 402) and nothing is generated. Saving content uses none.

You must provide either 'content' or 'instructions' (not both). The 'content' parameter cannot be used with blueprint_uuid.

Workflow:

1. Provide 'content' to save your own text directly as a document (the default for new content).
2. OR provide 'instructions' describing what to create (AI will generate it) — only when the user asks Marcora to write it, a blueprint is used, or a plan is being fulfilled.
3. Optionally provide blueprint_uuid from list_blueprints to generate from a template (instructions only).
4. Optionally get category_id from list_content_categories.
5. Optionally get dimension_option_ids from list_targeting_dimensions.
6. Optionally get collection_ids from list_context_collections.
7. Optionally set generation_mode (quick or multi_model); for Quick only, optionally set ai_provider and use_extended_thinking (default true; pass false for a faster run). Only applies with instructions.
8. Optionally provide reference_content_ids (content UUIDs from list_content) to fold existing content into the generation as reference material (instructions paths only).

PLAN INTEGRATION (additive — existing behavior unchanged):

• When the user has an active plan they want to fulfill, pass plan_id with the plan's UUID. The content will be linked to the plan and the plan will transition to In_Process automatically.
• plan_id is purely associative: the endpoint does NOT look up plan parameters server-side. Use get_plan to read prompt, blueprint_id, project_id, collection IDs, and targeting dimension IDs from the plan, then pass them explicitly here alongside plan_id.
• Do NOT pass plan_id if the plan is in Complete stage. Call get_plan first to verify the current stage. If Complete, call update_plan with target_stage='Accepted' to re-open it — confirm with the user — then call create_content.
• Linkage scope: plan_id triggers automatic plan↔content linking ONLY when used with blueprint_uuid (the async blueprint-generation path). The paths without blueprint_uuid (direct content, or instructions Quick or Multi-model) accept plan_id without error but do NOT currently establish the link automatically. For the standard plan-fulfillment flow, pass blueprint_uuid from the plan.
• Invalid plan_id is non-fatal: an invalid plan_id (not found, wrong format) is logged but content creation SUCCEEDS.

Only me material. An item marked audience: "only_me" is private to its owner. If this session read one, create_content saves the document as private (and keeps it restricted to its owner) rather than the team's. Never copy Only me text into a team-visible document without asking the user.

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.