Marcora

ask_content_assistant

Destructive

Sends a natural-language request to Marcora's in-document Content Assistant about ONE EXISTING content document (content_id, from list_content, get_content or get_project). The request can ask for an edit ("tighten paragraph two"), an extension, or pure ideation or a question ("give me three headline ideas"); the assistant decides whether to change the document or only reply. This is the in-editor Content Assistant, not the Marcora Agent.

It may rewrite the document body. It only does so when it decides the request warrants a change; otherwise it replies in the document's sidebar thread. Pass chat_only_mode=true to force a reply with no document change.

Asynchronous. It returns a generation_id at once and does the work in the background; it does not return the assistant's text. If the user has the document open in Marcora, the reply and any edits stream live into its AI Assistant sidebar. Headless callers poll get_generation_status with the generation_id.

One run per document at a time. A second call on the same document while a run is in progress fails with "Marcora is already updating this document." A run that may edit the document also holds it: nobody can edit it in the app until the run finishes or fails. A chat_only_mode=true run doesn't hold it. To send several requests, wait for each run to reach a terminal status, or combine them into one prompt. Never retry in a tight loop.

Context: the assistant sees the current document body, the prior sidebar conversation and relevant brand and reference context. Add collection_ids or project_id to fold in more.

Inputs: content_id and prompt (required); optional selected_text, thinking_mode, chat_only_mode, ai_provider, collection_ids, project_id.

Inputs:

content_id: the content document to act on (from list_content, get_content, or get_project).
prompt: the request, in natural language.
selected_text: optional text the user has highlighted in the document for the request to focus on.
thinking_mode: optional; enable extended reasoning for harder requests.
chat_only_mode: optional; force a reply-only response with no document edit.
ai_provider: optional model family (anthropic default, or openai).
collection_ids: optional Context Collection IDs to include.
project_id: optional project UUID to include its context.

Errors:

notfound: content_id matches no content document.
"Marcora is already updating this document.": another run on this document is still in progress. Wait for it to finish (poll get_generation_status if you have its generation_id), then retry.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "content_id": "<content_id>",
      "prompt": "<prompt>"
    },
    "name": "ask_content_assistant"
  }
}

Input Schema

Name	Required	Description
`prompt`	Yes	The request in natural language (an edit, an extension, or a question).
`content_id`	Yes	UUID of the content document to act on. Get from list_content, get_content, or get_project.
`project_id`	No	Project UUID (from list_projects) whose context to include.
`ai_provider`	No	Model family to use.
`selected_text`	No	Optional highlighted text in the document to focus the request on.
`thinking_mode`	No	Enable extended reasoning for complex requests.
`chat_only_mode`	No	Force a sidebar-only reply with no document changes.
`collection_ids`	No	Context Collection IDs (from list_context_collections) to include.

Output Schema

Name	Required	Description	Default
`status`	Yes	Initial status — always "pending" on dispatch.
`generation_id`	Yes	UUID identifying this assistant run.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 4, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Substantially exceeds the annotations: it discloses that the document body may be rewritten, that the run is asynchronous and returns only a generation_id, that execution is serialized per document with a lock that blocks in-app edits, and that chat_only_mode releases the lock. It also names the exact error string and the correct recovery (wait for terminal status, never retry in a tight loop) — consistent with destructiveHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded with bolded headings for the risky behaviors, and every section carries real information. There is mild duplication: the one-line "Inputs:" summary restates the required/optional split that the detailed bullet list immediately repeats, which could be collapsed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, yet the description still tells the agent the one thing it needs — that the immediate response is a generation_id and the text arrives via polling or live streaming. For an 8-parameter destructive async tool, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding facts the schema lacks, e.g. that ai_provider defaults to anthropic, that selected_text refers to a user highlight, and that collection_ids/project_id fold additional brand and reference context into the run.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("sends a natural-language request to Marcora's in-document Content Assistant") scoped to ONE existing document, and explicitly distinguishes itself from the similarly-named Marcora Agent. The parenthetical naming list_content/get_content/get_project tells an agent exactly where the id comes from.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit about when to use it (edit, extension, ideation or question on an existing doc) and when not to ("not the Marcora Agent"), plus a concrete alternative path: set chat_only_mode=true for reply-only, or combine multiple requests into one prompt instead of sequential calls. Headless callers are told to poll get_generation_status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Marcora tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?