Context & Resources

list_context_items

List context items from the team's library, each with its collection, project, and a link to open it in Marcora. By default it returns all items you can see; private items you don't have access to are filtered out. Pass a `search` query to rank items by semantic relevance instead of recency.

Parameters

Name	Type	Required	Default	Description
`reference_library_only`	`boolean`	No	—	Set true to return only the items that sit in no project and no collection — what the app shows as the "Reference Library". Leave it out (default false) to get everything you can see across projects, collections, and the reference library. Set it true when you want a clean view of unfiled material, for example to decide what still needs organising.
`search`	`string`	No	—	Optional natural-language query. When provided, items are ranked by semantic relevance to it (by their best-matching chunk) instead of recency, and each item gains a relevance_score. Omit or leave empty for the normal recency-ordered list. Scores are cross-comparable with list_content — call both with the same search, merge, and take the top matches by relevance_score.

Input Schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Optional natural-language query. When provided, items are ranked by semantic relevance to it (by their best-matching chunk) instead of recency, and each item gains a relevance_score. Omit or leave empty for the normal recency-ordered list. Scores are cross-comparable with list_content — call both with the same search, merge, and take the top matches by relevance_score."
    },
    "reference_library_only": {
      "type": "boolean",
      "description": "Set true to return only the items that sit in no project and no collection — what the app shows as the \"Reference Library\". Leave it out (default false) to get everything you can see across projects, collections, and the reference library. Set it true when you want a clean view of unfiled material, for example to decide what still needs organising."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "context_items"
  ],
  "properties": {
    "context_items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "link_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Context item ID. Pass to get_context_item to fetch full markdown."
          },
          "name": {
            "type": "string"
          },
          "added_by": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "description": "{id: integer, name: string} — the user who added the item."
          },
          "link_url": {
            "type": "string",
            "description": "URL to view this context item in the Marcora web app."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix timestamp of creation."
          },
          "project_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Project this item is associated with, or null."
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tracked web-page URL for webpage items; null otherwise."
          },
          "updated_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix timestamp of last update."
          },
          "word_count": {
            "type": "integer"
          },
          "content_type": {
            "type": "string",
            "description": "One of manual, webpage, canvas, deliverable, integration_data, call_transcript, file."
          },
          "collection_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Collection this item lives in, or null."
          },
          "content_intro": {
            "type": "string",
            "description": "Short truncation of the content for previews."
          },
          "relevance_score": {
            "type": [
              "number",
              "null"
            ],
            "description": "Semantic relevance to `search` (max cosine similarity across the item's chunks; higher = more relevant). ONLY present when `search` was supplied: a number means the item was scored against embedded chunks; null means it isn't embedded yet and couldn't be scored (sorted last). Absent entirely when no `search` was given. Cross-comparable with list_content relevance_score."
          },
          "relevancy_processed_status": {
            "enum": [
              "unprocessed",
              "provisional",
              "complete"
            ],
            "type": "string",
            "description": "Targeting-dimension processing state, for reference-library items only. Omitted entirely for items that belong to a project or a context collection. This does NOT indicate whether the item is embedded or retrievable — every context item is embedded for semantic search at ingestion regardless of this value."
          }
        }
      }
    }
  }
}

Instructions

Lists context items from the team’s context library.

By default returns ALL context items the user can see (across projects, collections, and the reference library). Set reference_library_only=true to return only items that are NOT in any project or collection — these are the items shown in the “Reference Library” section of the Marcora web app.

Each returned item carries its own collection_id and project_id (both nullable), so you always know where it lives. To get the full markdown content of any item, pass its id to get_context_item.

Semantic search (`search`)

Pass a natural-language search query to rank items by SEMANTIC relevance instead of recency — ranking is by each item's best-matching chunk. Each returned item then carries a relevance_score:

Absent (field not present) — no search was given; the list is ordered by recency.
A number (cosine similarity 0–1, higher = more relevant) — the item was scored against embeddings.
null — the item is not embedded yet and could not be scored; it sorts LAST.

Scores are cross-comparable with list_content. To find the best reference material across both context and content, call both tools with the SAME search, merge the results, and take the top matches by relevance_score. A typical flow: search → present the top matches to the user for confirmation → fetch full text with get_context_item / get_content → feed the chosen content content_ids into create_content's reference_content_ids to generate from them. reference_library_only composes with search.

Use search when the user asks to find or surface context by topic or meaning rather than browse the recency list.

Privacy: items in private collections (where you are not the creator) and items in private projects (where you are not a member) are filtered out — they will not appear in the response.

Other ways to discover context-item IDs:

get_project(project_id).context_items — items attached to a specific project
list_context_collections — items grouped by collection
get_relevant_context — returns context_item_ids of parent items for matched chunks

Example prompts:

“What context items do I have in Marcora?”
“Show me everything in my reference library”
“List the context items I haven’t filed into a collection or project”
“Find context about our competitors’ pricing”

Clients that previously read the bare array must now read response.context_items.