Tools Reference

This page documents every tool available through the Context Repo MCP Server. Each tool listing includes its exact parameters, types, and a brief usage example.

All tools require authentication. If you haven't connected your AI assistant yet, see the setup guides to get started.

User Info

get_user_info

Get your Context Repo account details including name, email, and profile image.

Parameters

None.

Example Usage

"What's my Context Repo account info?"

Returns your user ID, first name, last name, email address, and profile image URL.

Prompts

search_prompts

List one page of prompts in your workspace. The optional search value filters that fetched page by title or description only. Use find_items for semantic search or literal prompt-body matching.

Parameters

Example Usage

"List my prompts about code review"

Returns each prompt's title, description, public/private status, current version, and ID, plus pagination metadata. If hasMore is true, pass the returned cursor to the next search_prompts call.

read_prompt

Get the full content of a specific prompt including its template variables.

Parameters

Example Usage

"Show me the details of prompt abc123"

Returns the prompt's title, description, version number, public/private status, full content, and any ${variables} defined in the template.

create_prompt

Create a new prompt template. You can include variables using ${variableName} syntax in the content.

Parameters

Example Usage

"Create a prompt called 'Bug Report Template' that asks for a summary, steps to reproduce, and expected behavior"

Returns the new prompt's ID.

update_prompt

Update an existing prompt. Only provide the fields you want to change — everything else stays the same.

Parameters

Example Usage

"Update prompt abc123 to add a section about error handling, and note 'Added error handling section' in the changelog"

Returns the updated prompt's title and new version number.

delete_prompt

Permanently delete a prompt. This can't be undone.

Parameters

Example Usage

"Delete prompt abc123"

Returns a confirmation message.

get_prompt_versions

View a prompt's version metadata, change logs, and content previews up to 200 characters. The list doesn't return full historical prompt bodies.

Parameters

Example Usage

"Show me the version history for prompt abc123"

Returns each version's number, ID, author, change log entry, and a content preview.

restore_prompt_version

restore_prompt_version restores the selected version's content, parameters, and variables as a new version, so it doesn't overwrite history. Prompt title, description, tags, visibility, and other unversioned metadata remain at their current values.

Parameters

Example Usage

"Restore prompt abc123 to version xyz789"

Returns the new version number after restoration.

Documents

list_documents

List one page of documents in your workspace with optional title filtering.

Parameters

Example Usage

"List my documents about machine learning"

Returns each document's title, status, source type, creation date, and ID, plus pagination metadata. If hasMore is true, pass the returned cursor to the next list_documents call.

get_document

Get document content up to the REST response limit. Use deep_search for targeted retrieval from large documents.

Parameters

Example Usage

"Show me document def456"

Returns the document's title, status, source fields, canonical revision, currentVersion, contentHash, lastChangedAt, exact ETag, and content up to the REST response limit.

create_document

Create a new text document with optional tags.

Parameters

Example Usage

"Create a document called 'Meeting Notes - March 2026' with a summary of today's discussion, tagged with 'meetings' and 'engineering'"

Returns the new document's ID and tags.

update_document

MCP update_document and restore_document_version require expectedRevision, a nonnegative safe integer from get_document or the latest successful document acknowledgement. For restore, this is the current document revision, not the target historical version number.

Each invocation makes exactly one REST write with expectedRevision in the body and no preflight GET. On REVISION_MISMATCH, call get_document again. If the intended state is already present, stop. Otherwise, reapply the change to the latest content and retry with the returned revision.

Documents using lease_required managed editing must use the REST coordination workflow. MCP does not accept lease credentials.

Update an existing document. Only provide the fields you want to change.

Parameters

Example Usage

"Update document def456 with the revised introduction and log it as 'Rewrote introduction paragraph'"

Returns a compact acknowledgement with the ID, canonical revision, content hash, change time, and noop status. Exact unchanged values don't create a version.

delete_document

Permanently delete a document. This can't be undone.

Parameters

Example Usage

"Delete document def456"

Returns a confirmation message.

get_document_versions

View a document's complete version history with change logs.

Parameters

Example Usage

"Show me the version history for document def456"

Returns each version's number, ID, title, author, change log entry, and a content preview.

restore_document_version

Restore a document to a previous canonical snapshot. Complete and synthetic snapshots restore every canonical field; an exact unchanged restore is a no-op. The operation doesn't overwrite history.

Parameters

Example Usage

"Restore document def456 to version xyz789"

Returns the same compact acknowledgement as update_document. Restoring a legacy partial snapshot also returns warnings: ["LEGACY_PARTIAL_SNAPSHOT"]; fields absent from that historical snapshot are preserved.

Collections

list_collections

List one page of collections in your workspace with optional name filtering.

Parameters

Example Usage

"List my collections"

Returns each collection's name, description, icon, color, item count, and ID, plus pagination metadata. If hasMore is true, pass the returned cursor to the next list_collections call.

get_collection

Get details of a specific collection, optionally including up to 50 member items.

Parameters

Example Usage

"Show me the 'Frontend Prompts' collection with its member items"

Returns the collection's name, description, icon, color, item count, and, if includeItems is true, up to 50 prompts and documents in the collection. The tool doesn't expose a member cursor. Use the paginated REST collection-items endpoint when you need every member.

create_collection

Create a new collection to organize your prompts and documents.

Parameters

Example Usage

"Create a collection called 'Code Review' with a 🔍 icon and blue color #3b82f6"

Returns the new collection's ID, icon, and color.

update_collection

Update a collection's metadata. Only provide the fields you want to change.

Parameters

Example Usage

"Rename the collection ghi789 to 'Code Quality' and change its icon to ✅"

Returns a confirmation with the updated collection name.

delete_collection

Delete an empty collection. The collection must be empty, so remove all member items first. Removing an item from the collection does not delete the prompt or document from your workspace.

Parameters

Example Usage

"Delete collection ghi789"

Returns a confirmation after deleting the empty collection. A non-empty collection returns a conflict instead.

add_to_collection

Add prompts or documents to a collection. You can add multiple items at once.

Parameters

Example Usage

"Add prompts abc123 and abc456 to collection ghi789"

Returns the number of items added and how many were already in the collection.

remove_from_collection

Remove prompts or documents from a collection. The items themselves aren't deleted.

Parameters

Example Usage

"Remove document def456 from collection ghi789"

Returns the number of items removed.

Search

find_items

Search across prompts, documents, and collections using semantic similarity or keyword matching. This is the primary search tool — it returns item-level results (titles, IDs, relevance scores) across all content types.

For deep content exploration within documents, use Deep Search instead.

Parameters

Example Usage

"Find everything related to machine learning in my workspace"

Returns results grouped by type (prompts, documents, collections) with relevance scores for semantic search.

Structured output

structuredContent has this top-level shape:

{
  data: {
    prompts: Array<{
      promptId: string
      title: string
      description: string
      tags: string[]
      score?: number
      highlight?: string
    }>
    documents: Array<{
      documentId: string
      title: string
      tags: string[]
      score?: number
      highlight?: string
      chunkId?: string
    }>
    collections: Array<{
      collectionId: string
      name: string
      tags: string[]
      description?: string
      score?: number
      matchedItems?: number
    }>
  }
  meta: {
    query: string
    semantic: boolean
    latencyMs?: number
  }
}

The identifier field depends on the result type: promptId, documentId, or collectionId. find_items does not return a generic id field. Semantic results include scores; literal results may include a matching highlight, and document body matches may also include a chunkId.

find_items returns item-level metadata and optional snippets, not full stored content. Use read_prompt for full prompt content or get_document for document content up to the REST response limit. Use search followed by fetch when you need the ChatGPT Company Knowledge contract.

ChatGPT App compatibility

The search and fetch tools implement the OpenAI Apps SDK Company Knowledge contract used by the ChatGPT App.

search

Search your prompts, documents, and collections and return a flat list of citation-ready results.

Parameters

Each result contains an opaque id, a title, and a dashboard url. Pass the opaque id to fetch. Prompt IDs return full stored content; document IDs return content up to the REST response limit; collection IDs return metadata plus up to 50 member items.

fetch

Fetch full prompt content, document content up to the REST response limit, or collection metadata plus up to 50 member items, with a citation URL. Use deep_search for targeted retrieval from large documents.

Parameters

The response contains id, title, Markdown text, url, and type metadata.

Deep Search

Deep Search is a set of 3 tools for progressively exploring document content. Unlike find_items (which returns item-level catalog results), Deep Search returns granular content fragments with structural hierarchy — sections, paragraphs, and navigation links.

The typical workflow: start with deep_search to find relevant passages, use deep_read to examine a chunk in detail, and deep_expand to navigate through the document's structure.

deep_search

Search within document content using vector similarity and get ranked, hierarchical chunks with navigation links.

Parameters

Example Usage

"Deep search my documents for information about authentication best practices"

Returns ranked chunks, each with a chunkId, hierarchy level (document/section/paragraph), content preview, and navigation links (parent, siblings). Use the chunkId with deep_read or deep_expand to explore further.

deep_read

Read a single document chunk with full content and hierarchy metadata. Use this after deep_search to inspect a result in detail, or after deep_expand to examine a navigated chunk.

Parameters

Example Usage

"Read chunk abc123 in full"

Returns the chunk's complete text, structural position (section path, chunk index), navigation IDs (parent, previous sibling, next sibling), and content metadata (word count, heading text).

deep_expand

Navigate the document hierarchy from a chunk in 5 directions. Use this after deep_search to explore related content without re-searching.

Parameters

Directions

Example Usage

"Expand chunk abc123 downward to see its sub-sections"

Returns the chunks in the requested direction, each with its own chunkId for further navigation.

Reasoning

Reasoning is a single tool that sits one layer above Deep Search. Where deep_search returns ranked chunks for you to read, reason performs bounded retrieval and returns a best-effort cited answer projected from strict cited statements and limitations, with the exact chunks it cited and best-effort gaps. The gaps list is non-exhaustive. See Reasoning for a task-oriented guide.

reason

Ask a question and get a synthesized, cited answer composed across your documents — not a list of chunks. Read-only.

Parameters

The MCP tool doesn't expose maxTokens; the server uses the default 8000-token evidence budget. Use the REST endpoint when you need to set that budget.

Response

The readable MCP content always includes Answer and Meta, then adds Sources and Limitations when those arrays aren't empty. structuredContent preserves the REST response object.

Exact citation validation proves source linkage, not semantic entailment. Gaps remain bounded to best-effort limitations noticed during this run, including facts not established by the retrieved evidence within the requested scope and retrieval limits. They are non-exhaustive and do not prove repository-wide absence.

The tool uses at most one synthesis call with zero retries through a server-managed model. Empty evidence always skips synthesis. Weak unscoped evidence also skips synthesis. Nonempty explicit document or collection scope bypasses only Reason's fixed relevance gate. It operates on document content only and does not persist the answer or a reasoning trace. The strict provider result contains statements and limitations. Disagreements appear as ordinary cited statements in the answer.

Example Usage

"Using my documents, what is our refund policy for annual plans?"

Returns a cited answer that draws only on your stored content, with each claim traceable to a specific chunk via the citations array.

Related Pages