Tools Reference

The MCP server provides read tools for searching/querying the campaign knowledge base and write tools for the AI-powered recap publishing workflow.

Write-tool access

Recap write tools are for trusted MCP API-key callers and DM-controlled automation. The Slack-facing Foundry agent denies these write tool names during MCP approval, so players asking questions in Slack can use read/search behavior but cannot link documents, create drafts, generate images, publish, or unpublish recaps through Slack.

search

Search the corpus using hybrid search (vector similarity + keyword matching + trigram fuzzy matching). Returns relevant text chunks with source file, page numbers, section headings, and relevance scores.

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	—	The search query text
`maxResults`	integer	No	5	Maximum number of results to return (1–20)
`scope`	string	No	DM view	Visibility scope filter: `"all"` for player-visible content, `"dm-only"` for DM-only content, or omit for full DM view (both)
`sources`	string[]	No	All	Filter by source document IDs, filenames, or category names (e.g. `["#1", "rulebook.pdf"]`)
`categories`	string[]	No	All	Filter by category names (e.g. `["rules", "sessions"]`)

Example

Search for "critical hit damage" with maxResults 3 and categories ["rules"]

Response

Each result includes:

Score — Reciprocal Rank Fusion score combining all three search signals
Source file — The document the chunk came from
Page range — Which pages the chunk spans
Section heading — The nearest section heading (if available)
Content — The matching text passage

ask

Ask a question about rules, sessions, or campaign content. Uses retrieval-augmented generation (RAG) to provide answers grounded in the indexed corpus with source citations.

Parameters

Name	Type	Required	Default	Description
`question`	string	Yes	—	The question to ask
`scope`	string	No	DM view	Visibility scope filter: `"all"` for player-visible content, `"dm-only"` for DM-only content, or omit for full DM view (both)
`sources`	string[]	No	All	Filter by source document IDs, filenames, or category names
`categories`	string[]	No	All	Filter by category names

Example

Ask "How does advantage work?" with categories ["rules"]

Response

A generated answer citing source numbers, followed by a list of sources with file names, page ranges, and relevance scores.

list_documents

List all documents ingested into the corpus. Returns document names, chunk counts, page ranges, and ingestion dates.

Parameters

None.

Response

A formatted list showing:

Total document and chunk counts
Per-document: filename, document ID, category, visibility scope, chunk count, page range, and ingestion date

list_sources

List available document sources with their identifiers and visibility scopes. Use this to discover what values can be passed to the sources and categories parameters of search and ask.

Parameters

Name	Type	Required	Default	Description
`scope`	string	No	DM view	Visibility scope filter: `"all"` for player-visible content, `"dm-only"` for DM-only content, or omit for full DM view (both)

Response

A list of sources showing filename, document ID, category, visibility scope, and description.

read_document

Get the full text of a document from the corpus. Use this to read complete session transcripts or full document content instead of searching for individual chunks.

Parameters

Name	Type	Required	Default	Description
`source`	string	Yes	—	Source file name or document ID (e.g. `"rulebook.pdf"` or `"#5"`)

Response

The complete text content of the document.

link_campaign_document

Explicitly link an ingested document to a campaign's broad corpus.

Name	Type	Required	Description
`campaign`	string	Yes	Campaign ID or exact campaign name
`source`	string	Yes	Document source file or `#N` document ID

create_recap_draft

Create a player-safe AI recap draft for a first-class campaign session. This does not publish the recap.

Name	Type	Required	Description
`sessionId`	string	Yes	Campaign session GUID
`source`	string	No	Optional document source file or `#N` document ID; defaults to the session primary source

create_campaign_session

Create a dated first-class session for a campaign. Dates must be YYYY-MM-DD.

Name	Type	Required	Description
`campaign`	string	Yes	Campaign ID or exact campaign name
`playedOn`	string	Yes	Session played date in `YYYY-MM-DD` format
`sessionNumber`	integer	No	Optional campaign-local session number
`title`	string	No	Optional session title

list_campaign_sessions

List first-class campaign sessions for a campaign.

Name	Type	Required	Description
`campaign`	string	Yes	Campaign ID or exact campaign name

link_campaign_session_document

Link an ingested document to a first-class campaign session and optionally mark it as the primary recap source.

Name	Type	Required	Description
`sessionId`	string	Yes	Campaign session GUID
`source`	string	Yes	Document source file or `#N` document ID
`role`	string	No	Session document role, default `source`
`primary`	boolean	No	Whether to mark the document as the primary recap source

generate_recap_image

Generate and store one cinematic in-world hero image for a recap version.

Name	Type	Required	Description
`versionId`	string	Yes	Recap version GUID

This tool requires both Jime:ImageModelDeployment (an Azure OpenAI image deployment such as gpt-image-1) and Jime:StorageEndpoint so the generated image bytes can be stored in Blob Storage.

publish_recap

Publish an existing recap draft version. Publishing is explicit and separate from generation.

Name	Type	Required	Description
`versionId`	string	Yes	Recap version GUID

unpublish_recap

Hide a recap from the password-gated site.

Name	Type	Required	Description
`recapId`	string	Yes	Recap GUID

list_recaps

List published recaps and their private-preview URLs.

Parameters: none.

list_recap_versions

List all versions (draft, published, and archived) for a recap, newest first. Use this to discover stranded drafts or audit version history before generating new drafts.

Parameter	Type	Required	Description
`recapId`	string	Yes	Recap GUID

Filtering

The search, ask, and list_sources tools support filtering to narrow results:

By scope

Control which documents are visible based on audience:

Omit scope — Full DM view, includes both all and dm-only documents
scope: "all" — Player view, only documents marked as player-visible
scope: "dm-only" — DM-only documents, excludes player-visible content

By source

Pass specific document identifiers to the sources parameter:

File name — "rulebook.pdf"
Document ID — "#1" (use list_sources to discover IDs)

By category

Pass category names to the categories parameter. Categories are free-form labels assigned by the DM (e.g. "rules", "sessions", "npcs").

Tip

Use list_sources first to see available documents, their IDs, and categories. Then use those values to filter search and ask queries.