create_content

Use this tool to create content. You can create content from scratch using an AI prompt, supply your own content directly, or generate from a blueprint.

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 — this matters:

• instructions (Marcora writes it): this tool internally pulls all relevant context — Brand Foundation + Reference Library (relevancy-scored) + Project Context (if project_id is set) + any Context Collections you pass in collection_ids. Do NOT pre-fetch with get_relevant_context — that's wasted work. Just pass any explicit collection_ids / dimension_option_ids you want included and let this tool gather everything else.
• content (you supply finished text): this tool stores your markdown VERBATIM and consults NO context — not Brand Foundation, not the Reference Library, not Project Context. If YOU are composing the content yourself, call get_relevant_context with include_brand_foundation: true FIRST and write from what it returns; otherwise your draft ignores the team's brand and reference material.

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: to get something written against the team's full context automatically, prefer instructions and let Marcora generate it. Use content to save text the user already wrote or approved — or when the user specifically wants YOU (the AI agent) to do the writing, in which case ground yourself with get_relevant_context first (see above).

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) (synchronous):
Creates a freeform document from an AI prompt. SYNCHRONOUS — typically takes 1-3 minutes. Returns the content object directly.

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.

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.
2. OR provide 'instructions' describing what to create (AI will generate it).
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. Set use_extended_thinking=true for complex content (only applies with instructions, without blueprint).
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 synchronous paths (direct content, or instructions without blueprint_uuid) 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.

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.