add_context
Adds a new context item to the team's reference library: reference material (product facts, positioning, competitor notes, web pages) that Marcora uses to ground AI-generated content.
Give a descriptive name, then the body in EXACTLY ONE of three ways (none, or more than one, is rejected):
content: paste the markdown body. Best for short or hand-authored material. Creates a plain text item.import_url: a public URL imported ONCE. The page is fetched and converted to clean markdown server-side and stored as a static snapshot that cannot be refreshed. Use it for one-off imports (an exported document link, a competitor's blog post).connected_webpage_url: a URL tracked as a live web page. It is fetched, stored as a "webpage" item, and the URL is remembered so it can be re-pulled later (update_contextrefresh_webpage, or the refresh button in the app). Use it for the customer's own pages and anything to keep current. If the URL is already tracked, the existing item is UPDATED in place (no duplicate) and its stored content is OVERWRITTEN with the fresh fetch. Requires admin or editor role.
Both URL paths wait for the import, up to about 25 seconds. If the page loads in that time the response has import_status "ready" (get_context_item returns the body). If the page can't be read the call returns an error and nothing is added (a tracked page keeps its saved copy). Only a slow page returns import_status "processing" with a real context item id; for what polling shows and how long to wait, see Polling below.
Optionally pass collection_id (see list_context_collections / create_context_collection) and/or project_id (see list_projects) to create the item there directly. These apply to all three paths.
Present the returned link_url (it opens the new item in the Marcora web app) exactly as returned.
Call transcripts: text that looks like a call transcript (WebVTT or SRT, or lines with speaker labels and timestamps) is saved as a call in Calls, as the Add form does, and the result says so (saved_as_call: true). Pass as_call: true to save any text as a call, or as_call: false to keep it an ordinary context item. A call is Only me (visible only to the person who added it) unless you pass audience: "team"; ask the user if you are unsure who should see it. Optional call details: call_date (ISO 8601), call_kind, call_company; anything left out is worked out from the transcript. A call takes content only. call_date, call_kind, call_company and audience: "only_me" apply to calls only: sending one for text saved as an ordinary item is rejected rather than ignored. The summary is written after the save; call.summary_status shows where it is, and get_context_item returns the summary once ready.
Team audience on ordinary items: when the user asks for the item to be saved for the team, pass audience: "team" (on content, import_url or connected_webpage_url), even with a collection_id or project_id. It is accepted when the item will be team-visible. In a private collection or private project it is refused with an error and nothing is saved: tell the user why and offer a shared collection, a team-visible project or the Reference Library. Never fall back to a private save without asking the user.
Importing calls from a connected app: a fourth way, import_from: { toolkit, call_ids }, brings in calls the user keeps in a call-recording app. Use it instead of content, import_url and connected_webpage_url, and without as_call, call_date, call_kind or call_company. First find the calls with the app's own list or search tool in your session, then pass their ids (1 to 10) in this ONE call: Marcora fetches and cleans each transcript itself through the user's own connection, so never retype or paste a transcript. toolkit is fathom, gong, fireflies, googlemeet or wispr_flow_mcp. Google Meet and Wispr Flow imports are Beta. For Google Meet, pass the bare ID from conferenceRecords/{id}, or doc:{document_id} for a saved transcript. Recent discovery is organizer-only within 30 days; a known conference record still requires access. Saved transcripts require your own active Google Meet and Google Docs connections in the same team; discovery also requires Google Drive and searches by document creation window. The document must contain a date and timestamped speaker-labelled transcript, not just Gemini notes. Meet supplies no original meeting title or participant emails; automatic Meet imports stay Only me and do not support attendance filters. For Wispr Flow, use a meeting ID from search: recorded meetings only, not dictation or scratchpad. Wispr attendee search uses calendar invitees; narrow a search that reaches 1,000 matches. audience, project_id and collection_id work as they do for calls (Only me and filed in Calls unless you say otherwise; a Collaborator must pass project_id; choose one of project_id or collection_id). name is ignored here because each call keeps its own title. The result lists every call as imported, duplicate, not_ready or failed, with where it was filed and who can see it, and never includes transcript text. If the app is not connected the call fails with an error that names the app and carries its Connect link: give the user that link, and retry once they have connected. When at least one call was imported the result carries automatic_import_link: offer it so the user can set up automatic import; it opens the rule editor with these choices filled in and nothing is saved until the user saves it. To find out whether an app is connected, or to get a Connect link before importing, use find_app.
Polling after "processing": get_context_item has no import_status. import_url: not found until the import finishes, then the item with its content. connected_webpage_url: the item exists at once with empty content (word_count 0) until the fetch lands; if the fetch fails a new page is removed (not found) and a tracked page keeps its saved copy. Poll for up to about 5 minutes; if the save is still unconfirmed, tell the user it couldn't be confirmed yet and do not re-add the URL yourself (a retry can create a duplicate). A failed slow import sends the user a "wasn't saved" notification.
Plan capacity: a processing import_url does not reserve a slot: if another add fills the plan's last slot, the import is refused when it finishes and adds nothing; a new web page holds its slot from the start. At the limit, a call that would create a context item (content, import_url or a new web page) returns an error stating the limit: deleting an item makes room. Re-adding a connected_webpage_url the team already tracks still refreshes it.
Extraction: both URL paths use AI main-content extraction: it isolates the primary page or article body and drops navigation and boilerplate. A connected_webpage_url fetch can fail when the page is unreachable or blocks automated requests.
Links: copy link_url character for character. Never retype, shorten, or rebuild a link or the IDs inside it.
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": {
"name": "<name>"
},
"name": "add_context"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Short, descriptive label for this reference item, shown in the library list and used when the AI cites it — make it specific enough to tell similar items apart ("Q3 Pricing Page" rather than "Pricing"). Required. When tracking a live web page, an empty name falls back to the page's own title. | |
| as_call | No | Whether to save `content` as a call transcript in Calls. Omit it and Marcora decides: text that looks like a transcript becomes a call. true: save as a call even if it does not look like one. false: save as an ordinary context item even if it looks like a transcript. Only valid with `content`. | |
| content | No | The item's body as markdown, pasted inline. Best for short or hand-authored material — it is stored as-is and embedded for retrieval immediately, so the item is usable the moment the call returns. Exactly one of content, import_url, or connected_webpage_url must be set; sending none, or more than one, is rejected (an empty string counts as not set). | |
| audience | No | Who can see it. For a call: only_me (default; visible only to the person who added it) or team. For an ordinary context item: pass team when the user wants it saved for the team, even with a collection_id or project_id; in a private collection or project it is refused and nothing is saved, so tell the user and offer a shared collection, a team-visible project or the Reference Library, and never save privately without asking. only_me is rejected on an ordinary item. | |
| call_date | No | Calls only. When the call happened, as YYYY-MM-DD or an ISO 8601 timestamp. Omit it to take the date from the transcript. | |
| call_kind | No | Calls only. The kind of call: customer (a customer call), external (a meeting with people outside the team), team_meeting, one_on_one, recorded (a recorded talk or other single-speaker recording). Omit it to let Marcora work it out from who spoke. | |
| import_url | No | A publicly reachable URL to fetch ONCE and store as a static markdown snapshot; the snapshot can never be refreshed. Use it for one-off material — a competitor's post, an exported doc behind a temporary link. Exactly one of content, import_url, or connected_webpage_url may be set (none or two-plus is rejected), and the call waits up to about 25 seconds for the import: import_status "ready" on success, an error if the page can't be read (nothing is added), or "processing" only for a slow page. In that case the item does not exist until the import finishes: poll get_context_item with the returned id for up to about 5 minutes (not found, then the item with its content); if it is still not found, tell the user the save couldn't be confirmed yet and do not re-add the URL yourself. A failed slow import sends the user a "wasn't saved" notification. | |
| project_id | No | UUID of a project to attach this item to, from list_projects, so it shows up as that project's reference material. Omit it to leave the item unattached to any project. The project must belong to your team or the call fails, and users with the collaborator role can only add reference material inside a project, so for them this is effectively required. | |
| import_from | No | Bring in calls from a connected call-recording app instead of passing text. Use it instead of content, import_url and connected_webpage_url (it cannot be combined with them or with as_call, call_date, call_kind or call_company). Marcora fetches and cleans the transcripts itself; never pass transcript text. audience, project_id and collection_id apply as for calls. | |
| call_company | No | Calls only. The other company on the call (null for none). Omit it to take the company from the transcript. | |
| collection_id | No | Numeric ID of the collection to file this item in, from list_context_collections or create_context_collection. Omit it (or pass null or 0) to leave the item loose in the reference library. The collection must belong to your team, and a private collection must be one you created — otherwise the call is rejected. | |
| connected_webpage_url | No | A URL to track as a live page: the page is fetched and its URL is stored, so the item can be re-pulled later with update_context refresh_webpage. Use it for the customer's own pages and anything you want to keep current; re-adding a URL the team already tracks updates that item in place rather than creating a duplicate. Exactly one of content, import_url, or connected_webpage_url may be set (none or two-plus is rejected), and adding a tracked page requires an admin or editor role. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Context item ID | |
| call | No | Call details; present only on call items. | |
| name | No | Context item name | |
| content | No | The stored reference content. Always null on add_context for import_url and connected_webpage_url items, ready or not: fetch the body with get_context_item. null for pasted content too. | |
| message | No | Calls only. Where it went and who can see it; tell the user. | |
| results | No | Present only on an import_from add: one entry per requested call, in order. | |
| summary | No | Present only on an import_from add: how many calls ended in each state. | |
| audience | No | Calls only. Who can see it. | |
| link_url | No | URL to view this context item in the Marcora web app. | |
| project_id | No | Project association (if assigned) | |
| word_count | No | Word count of content (0 while an import / webpage fetch is still processing) | |
| import_from | No | Present only on an import_from add: which app the calls came from. | |
| content_type | No | manual (content/import_url), webpage (connected_webpage_url) or call_transcript (a call) | |
| collection_id | No | Collection this item belongs to (if assigned) | |
| import_status | No | For import_url and connected_webpage_url items: ready once loaded (the call waits up to about 25 seconds); processing only if the import is still running after that. get_context_item has no import_status: for import_url the item is not found until it finishes, for connected_webpage_url it exists at once with empty content until the fetch lands. null for pasted content. | |
| saved_as_call | No | True when saved as a call. | |
| automatic_import_link | No | Present only when at least one call was imported. Opens the automatic-import rule editor with this source, destination and audience filled in; nothing is saved until the user saves it. Offer it, exactly as returned. | |
| brand_foundation_build | No | Present only on a connected_webpage_url add that queued a build of the team's blank Brand Foundation sections from the website. Absent otherwise, so never imply a build is running without it. |