MCP Tools
Context & Resources

get_relevant_context

Searches the team's context library and returns the most relevant chunks for a prompt, with per-source citation metadata and optional Brand Foundation.

Parameters

NameTypeRequiredDefaultDescription
promptstringYes—Search prompt describing the topic/question. Be specific.
project_iduuidNo—**Additive** — ALSO searches that project's context alongside the general library. Not an exclusive filter.
collection_idsinteger[]No—**Additive** — ALSO searches those collections alongside the general library. Not an exclusive filter.
context_rag_idsuuid[]No—Previously-returned chunk IDs to exclude (pagination — pass back the `context_rag_ids` from a prior call).
dimension_option_idsinteger[]No—Targeting dimension OPTION IDs (from `list_targeting_dimensions`) — biases relevancy toward an audience/persona/industry.
include_brand_foundationbooleanNo—When `true`, also returns the team's Brand Foundation in the response. Default `false`. Recommended `true` on the **first** call of a conversation (and when paginating, the first page), then `false`/omit on follow-ups so it isn't re-sent each time

Input Schema

{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "description": "Search prompt describing the topic/question. Be specific."
    },
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "Additive — ALSO searches that project's context alongside the general library. Not an exclusive filter."
    },
    "collection_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Additive — ALSO searches those collections alongside the general library. Not an exclusive filter."
    },
    "context_rag_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Previously-returned chunk IDs to exclude (pagination — pass back the context_rag_ids from a prior call)."
    },
    "dimension_option_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Targeting dimension OPTION IDs (from list_targeting_dimensions) — biases relevancy toward an audience/persona/industry."
    },
    "include_brand_foundation": {
      "type": "boolean",
      "description": "Set true to also receive the team's Brand Foundation in the same response. Default false."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "link_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Deep-link that opens this item in the Marcora web app. Present for every source."
          },
          "project_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The project the item belongs to, if any."
          },
          "source_url": {
            "type": "string",
            "description": "The original external page URL. Present only for webpage items; omitted for all other types."
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "One of: file, manual, webpage, canvas, deliverable, integration_data, call_transcript."
          },
          "last_updated": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix-ms timestamp of the item's last update (null if never updated)."
          },
          "collection_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The collection the item belongs to, if any."
          },
          "context_item_id": {
            "type": "string",
            "format": "uuid",
            "description": "The parent context item's ID."
          },
          "context_rag_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The chunk IDs in THIS response that came from this item. Union across all sources equals the top-level context_rag_ids."
          },
          "context_item_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The item's name."
          }
        }
      },
      "description": "One entry per parent context item the returned chunks came from."
    },
    "retrieval": {
      "type": "object",
      "properties": {
        "project_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Echo of the project_id input."
        },
        "team_scope": {
          "type": "string",
          "description": "Always authenticated_user_active_team."
        },
        "collection_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Echo of the collection_ids input."
        },
        "returned_count": {
          "type": "integer",
          "description": "Number of context chunks returned."
        },
        "dimension_option_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Echo of the dimension_option_ids input."
        },
        "excluded_context_rag_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Echo of the context_rag_ids input (the exclusions)."
        }
      },
      "description": "Echo of the search scope this response was produced under."
    },
    "context_rag_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "All chunk IDs returned. Pass back in context_rag_ids to exclude on the next page (pagination)."
    },
    "brand_foundation": {
      "type": "object",
      "properties": {
        "elements": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "brand_voice": {
              "type": "string"
            },
            "writing_style": {
              "type": "string"
            },
            "company_overview": {
              "type": "string"
            },
            "writing_examples": {
              "type": "string"
            }
          },
          "description": "Null unless included. When present: company_overview, brand_voice, writing_style, writing_examples (all strings)."
        },
        "included": {
          "type": "boolean",
          "description": "True only when include_brand_foundation: true was passed."
        },
        "link_url": {
          "type": "string",
          "description": "Deep-link to the Brand Foundation tab in the Marcora web app. Present only when included."
        }
      },
      "description": "Always present. included=true only when include_brand_foundation was passed; elements is null otherwise."
    },
    "relevant_context": {
      "type": "string",
      "description": "Ready-to-use markdown context packet assembled from the matched chunks."
    }
  }
}

Instructions

get_relevant_context returns the most relevant context chunks from the team's library for a given prompt, assembled into a ready-to-use markdown packet. Alongside the packet it now returns a structured sources array so an MCP client can cite and deep-link each source without follow-up lookups, a retrieval object echoing the search scope, and (optionally) the team's Brand Foundation. Use it when you need to read context yourself to answer a question or ideate — NOT before create_content, which pulls context in automatically.

Important — additive scoping: collection_ids and project_id BROADEN the search; they add those items on top of the general reference library, they do NOT restrict results to only that collection/project. (Same semantics as project context.)

Set include_brand_foundation: true to also receive the team's Brand Foundation (company overview, brand voice, writing style, writing examples) in the same response — a one-stop fetch of everything you need to write on-brand yourself with your own model. (You don't need it when handing off to create_content, which pulls Brand Foundation in automatically.)

Tip — bundle Brand Foundation on the first call: Default the first get_relevant_context call of a conversation to include_brand_foundation: true. Brand Foundation is always-on foundational context that relevancy scoring never surfaces on its own; pulling it in once, up front, means the agent has the team's company overview and brand voice on hand for the rest of the session — useful even when just answering a question. On subsequent calls in the same conversation, set it false/omit so it isn't re-sent each time.

For Brand Foundation specifically (brand voice, company overview, writing style, writing examples), relevancy search will not return those elements — use get_brand_foundation, or include_brand_foundation: true above. A "what is our brand voice?" question can't be answered from relevancy chunks alone.

Response Shape

Top-level keys: relevant_context, brand_foundation, retrieval, context_rag_ids, sources. (The old top-level context_item_ids is removed — each source now carries its own context_item_id.)

Top-Level Fields

Field Type Description
relevant_context string Ready-to-use markdown context packet assembled from the matched chunks.
context_rag_ids uuid[] All chunk IDs returned. Pass back in context_rag_ids to exclude on the next page (pagination).
brand_foundation object Always present. See below.
retrieval object Echo of the search scope this response was produced under. See below.
sources object[] One entry per parent context item the returned chunks came from. See below.

brand_foundation Object

Field Type Description
included boolean True only when include_brand_foundation: true was passed.
elements object | null Null unless included. When present: company_overview, brand_voice, writing_style, writing_examples (all strings).
link_url string Deep-link to the Brand Foundation tab in the Marcora web app. Present only when included.

retrieval Object

Field Type Description
team_scope string Always authenticated_user_active_team.
project_id uuid | null Echo of the project_id input.
collection_ids integer[] Echo of the collection_ids input.
dimension_option_ids integer[] Echo of the dimension_option_ids input.
excluded_context_rag_ids uuid[] Echo of the context_rag_ids input (the exclusions).
returned_count integer Number of context chunks returned.

sources[] — Each Entry

Field Type Description
context_item_id uuid The parent context item's ID.
context_item_name string | null The item's name.
content_type string | null One of: file, manual, webpage, canvas, deliverable, integration_data, call_transcript.
link_url string | null Deep-link that opens this item in the Marcora web app. Present for every source.
source_url string The original external page URL. Present only for webpage items; omitted for all other types.
collection_id integer | null The collection the item belongs to, if any.
project_id uuid | null The project the item belongs to, if any.
last_updated integer | null Unix-ms timestamp of the item's last update (null if never updated).
context_rag_ids uuid[] The chunk IDs in THIS response that came from this item. The union across all sources equals the top-level context_rag_ids.

Citing sources: every returned chunk is attributed to exactly one entry in sources (the per-source context_rag_ids partition the top-level set). Use link_url to deep-link any source into the Marcora app; for webpage items, source_url is the original external page.

Examples

Retrieve context on a topic and cite sources

Search for relevant context on competitor pricing and get back structured source attribution.

Input
{
  "prompt": "What do we have on competitor X's pricing?"
}
Output
{
  "relevant_context": "## Competitor X Pricing\n\nCompetitor X offers three tiers...",
  "context_rag_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "brand_foundation": {
    "included": false,
    "elements": null
  },
  "retrieval": {
    "team_scope": "authenticated_user_active_team",
    "project_id": null,
    "collection_ids": [],
    "dimension_option_ids": [],
    "excluded_context_rag_ids": [],
    "returned_count": 1
  },
  "sources": [
    {
      "context_item_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "context_item_name": "Competitor Battlecard Q2",
      "content_type": "file",
      "link_url": "https://app.marcora.ai/context/f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "collection_id": null,
      "project_id": null,
      "last_updated": 1717200000000,
      "context_rag_ids": [
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      ]
    }
  ]
}

Pull positioning with Brand Foundation included

Fetch healthcare positioning context AND the team's Brand Foundation in a single call for on-brand drafting.

Input
{
  "prompt": "Pull our healthcare positioning",
  "include_brand_foundation": true
}
Output
{
  "relevant_context": "## Healthcare Positioning\n\nOur platform is purpose-built for...",
  "context_rag_ids": [
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ],
  "brand_foundation": {
    "included": true,
    "elements": {
      "company_overview": "MarketCore is a B2B marketing platform...",
      "brand_voice": "Confident, direct, jargon-free",
      "writing_style": "Active voice, second person, short sentences",
      "writing_examples": "See example 1..."
    },
    "link_url": "https://app.marcora.ai/brand-foundation"
  },
  "retrieval": {
    "team_scope": "authenticated_user_active_team",
    "project_id": null,
    "collection_ids": [],
    "dimension_option_ids": [],
    "excluded_context_rag_ids": [],
    "returned_count": 1
  },
  "sources": [
    {
      "context_item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "context_item_name": "Healthcare Vertical Positioning",
      "content_type": "manual",
      "link_url": "https://app.marcora.ai/context/c3d4e5f6-a7b8-9012-cdef-123456789012",
      "collection_id": 42,
      "project_id": null,
      "last_updated": 1717200000000,
      "context_rag_ids": [
        "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      ]
    }
  ]
}

Paginate for more context on the same topic

Pass the prior call's context_rag_ids back to get additional chunks without repeating what was already returned.

Input
{
  "prompt": "More context on healthcare positioning",
  "context_rag_ids": [
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}
Output
{
  "relevant_context": "## Additional Healthcare Context\n\nFurther detail on...",
  "context_rag_ids": [
    "d4e5f6a7-b8c9-0123-defa-234567890123"
  ],
  "brand_foundation": {
    "included": false,
    "elements": null
  },
  "retrieval": {
    "team_scope": "authenticated_user_active_team",
    "project_id": null,
    "collection_ids": [],
    "dimension_option_ids": [],
    "excluded_context_rag_ids": [
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ],
    "returned_count": 1
  },
  "sources": [
    {
      "context_item_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "context_item_name": "Healthcare Case Studies 2025",
      "content_type": "file",
      "link_url": "https://app.marcora.ai/context/e5f6a7b8-c9d0-1234-efab-345678901234",
      "collection_id": 42,
      "project_id": null,
      "last_updated": 1717200000000,
      "context_rag_ids": [
        "d4e5f6a7-b8c9-0123-defa-234567890123"
      ]
    }
  ]
}
Scroll to Top