Documentation MCP Tools

All Documentation MCP tools are read-only and idempotent. They do not change documents, user data, or external systems.

Tool Summary

Tool	Required input	Optional input	Primary output
`resolve_docs_action`	`action`	`context`, `section`, `maxDocuments`, `maxCharsPerDocument`	Intent-aware reading plan and evidence pack
`research_docs`	`goal`	`codeContext`, `section`, `maxDocuments`	Ordered, multi-source reading plan
`search_docs`	`query`	`context`, `section`, `limit`	Ranked document passages
`read_documents`	`paths`	`maxCharsPerDocument`	Multi-source evidence pack
`get_document`	`path`	None	Complete Markdown document
`find_related_docs`	`path`	`limit`	Linked and topically related documents
`list_doc_sections`	None	`section`	Document count and page list

`resolve_docs_action`

This is the primary tool for normal AI usage. Pass the user's requested action without reducing it to search keywords. The action can be a direct question, explanation, comparison, recommendation, summary, troubleshooting request, implementation task, or another documentation-grounded request.

The tool:

Detects the likely intent.
Expands the request into several complementary retrieval lanes.
Selects diverse heading-level matches instead of returning only repeated overview content.
Reads the selected documents.
Returns a citation-ready evidence pack and instructions for synthesis.

Input

Field	Type	Required	Constraints	Description
`action`	string	Yes	3–2,000 characters	Complete user request or desired action.
`context`	string	No	Maximum 6,000 characters	Conversation details, environment, constraints, inspected code facts, or prior decisions.
`section`	string	No	Maximum 100 characters	Optional top-level documentation section filter.
`maxDocuments`	integer	No	2–8; default `5`	Maximum sources selected and read.
`maxCharsPerDocument`	integer	No	2,000–20,000; default `12,000`	Maximum Markdown read from each source.

Example for a normal question:

{
  "action": "Explain how catalog webhooks work, when a merchant should use them, and which security controls are required.",
  "section": "merchant-services"
}

Example with non-code context:

{
  "action": "Compare the available agent protocols and recommend the best fit for a product discovery assistant.",
  "context": "The assistant only needs read access to one store and must not expose internal fields."
}

Example with code context:

{
  "action": "Create a Merchant Services integration roadmap for this application.",
  "context": "Next.js storefront; PostgreSQL catalog; checkout routes exist; no API client or webhook receiver.",
  "section": "merchant-services",
  "maxDocuments": 8
}

Output

The structured result includes detectedIntent, inferred topics, the selected readingPlan, document Markdown, related-document suggestions, truncation state, public URLs, and synthesis instructions. Supported intent labels are answer, explain, compare, recommend, summarize, troubleshoot, and implement.

The MCP client remains responsible for the final natural-language or structured output. It should combine relevant facts across the returned sources, cite the URLs it uses, preserve supplied context separately from documented facts, and fetch a complete document when a required source is truncated.

`research_docs`

Use this as the first documentation tool for implementation plans, architecture decisions, migrations, and roadmaps. It combines the user goal with facts collected from the codebase, expands the task into several domain-specific searches, follows useful document links, and returns a dependency-ordered reading plan.

The tool does not invent the final roadmap. It selects evidence that the calling agent must read and reconcile with the code.

Input

Field	Type	Required	Constraints	Description
`goal`	string	Yes	5–1,500 characters	User objective or implementation question.
`codeContext`	string	No	Maximum 6,000 characters	Concise facts observed in the code: stack, APIs, auth, data models, integrations, and constraints.
`section`	string	No	Maximum 100 characters	Optional top-level documentation section filter.
`maxDocuments`	integer	No	3–12; default `8`	Maximum documents in the reading plan.

Example:

{
  "goal": "Create a Merchant Services integration roadmap for this application",
  "codeContext": "Next.js storefront; existing product API and checkout routes; PostgreSQL product table; no webhook receiver; bearer-token secrets already use server-only environment variables.",
  "section": "merchant-services",
  "maxDocuments": 8
}

Output

The result includes:

inferredTopics: normalized domain terms used during retrieval.
readingPlan: documents ordered into roadmap stages such as prerequisites, security, data mapping, implementation, events, and operations.
reason: retrieval lanes that made each document relevant.
matchedHeadings and excerpt: evidence for selecting the source.
nextActions: explicit instructions to read sources, compare them with code, follow gaps, and cite URLs.

After this call, pass the selected readingPlan[].path values to read_documents. Do not draft a detailed roadmap from the excerpts alone.

`search_docs`

Search published Thyris documentation by question, phrase, API name, endpoint, or topic.

Input

Field	Type	Required	Constraints	Description
`query`	string	Yes	2–300 characters	Text to search for.
`context`	string	No	Maximum 3,000 characters	Concise code or task context used for ranking and domain expansion.
`section`	string	No	Maximum 100 characters	Optional top-level section filter.
`limit`	integer	No	1–10; default `5`	Maximum results to return.

Example arguments:

{
  "query": "catalog webhook x-webhook-secret validation",
  "context": "Node.js backend with an existing product sync job",
  "section": "merchant-services",
  "limit": 3
}

Output

{
  "query": "catalog webhook x-webhook-secret validation",
  "resultCount": 1,
  "results": [
    {
      "title": "Catalog Webhook Integration Guide for Merchants",
      "path": "merchant-services/16-merchant-webhook-implementation-playbook.md",
      "url": "https://docs.thyris.ai/docs/merchant-services/16-merchant-webhook-implementation-playbook",
      "score": 66,
      "matchedHeadings": ["4. Inbound Authentication", "22. Security Controls"],
      "matchedTerms": ["catalog", "webhook", "x-webhook-secret", "validation"],
      "excerpt": "...best matching heading-level excerpt...",
      "supportingChunks": []
    }
  ]
}

Output field	Description
`resultCount`	Number of results returned, not the total number of indexed documents.
`score`	Internal relevance score. Compare scores only within the same search response.
`path`	Canonical source path accepted by `get_document`.
`url`	Public documentation URL for attribution or user navigation.
`excerpt`	A bounded Markdown excerpt centered near a discriminating query term.

Search is case-insensitive and normalizes punctuation and diacritics. It searches heading-level passages, applies inverse-document-frequency weighting, rewards term coverage, expands known Thyris domain vocabulary, and ranks exact phrase, title, heading, path, description, and body matches differently.

Recommended workflow:

Search with a focused query.
Inspect the top titles, URLs, and excerpts.
Call get_document with the selected path when more context is needed.
Answer using the returned content and public URL.

`read_documents`

Read up to eight selected documents in one bounded call. Use it when the client needs manual control over the sources for a question, comparison, summary, troubleshooting request, or implementation task.

Input

Field	Type	Required	Constraints	Description
`paths`	string[]	Yes	1–8 unique paths	Canonical paths in reading order.
`maxCharsPerDocument`	integer	No	2,000–30,000; default `18,000`	Per-document Markdown limit.

The entire evidence pack is capped at 80,000 characters. Each returned document includes its title, path, URL, headings, Markdown, truncation state, and a small set of related documents. Missing paths are returned separately rather than failing the complete batch.

When truncated is true and the omitted material is relevant, the agent should call get_document for that source before producing its answer.

The result includes a synthesis instruction requiring the agent to fulfill the user's request by combining relevant details across sources, citing the returned URLs, and keeping documented facts separate from inference, recommendations, and supplied context. When code context is available, the agent should also distinguish observed code facts and implementation gaps from documentation requirements.

`find_related_docs`

Follow the documentation graph when the current evidence is incomplete.

Input

Field	Type	Required	Constraints	Description
`path`	string	Yes	1–500 characters	Source path or URL.
`limit`	integer	No	1–12; default `6`	Maximum related documents.

Relationship types are:

Relation	Meaning
`linked_from_document`	The selected document links directly to this page.
`links_to_document`	This page links back to the selected document.
`similar_topic`	Passage retrieval found strong topical overlap in the same section.

Read only related documents that close a concrete gap, such as missing authentication, payload fields, webhook behavior, testing, or operational requirements.

`get_document`

Read one complete published documentation page as Markdown.

Input

Field	Type	Required	Constraints	Description
`path`	string	Yes	1–500 characters	Document path, document ID, or `docs.thyris.ai` URL.

Accepted identifier forms include:

merchant-services/03-authentication-and-scopes.md
merchant-services/03-authentication-and-scopes
docs/merchant-services/03-authentication-and-scopes
https://docs.thyris.ai/docs/merchant-services/03-authentication-and-scopes

Use the exact path returned by search_docs for the most reliable lookup.

Output

The tool's text content block contains the title, source URL, and complete Markdown so every compatible client can consume the document without receiving the large body twice. Its structured content contains navigation metadata:

{
  "title": "Authentication And Scopes",
  "path": "merchant-services/03-authentication-and-scopes.md",
  "url": "https://docs.thyris.ai/docs/merchant-services/03-authentication-and-scopes",
  "section": "merchant-services",
  "headings": ["Authentication And Scopes", "Authentication"],
  "relatedDocuments": []
}

Not-found error

An unknown identifier returns a tool error:

Document not found: <path>. Use search_docs to find the canonical path.

When this occurs, search for the document and retry with the returned path.

`list_doc_sections`

List published pages and report their count. Use it for navigation, inventories, and section-level discovery rather than normal topic questions.

Input

Field	Type	Required	Constraints	Description
`section`	string	No	Maximum 100 characters	Top-level documentation directory to restrict results.

Common section values:

about-thyris
merchant-services
acp-engine
safe-zone
thyris-ui
documentation-mcp

Example arguments:

{
  "section": "thyris-ui"
}

Omit section to list and count all published documents:

{}

Output

{
  "section": "thyris-ui",
  "documentCount": 7,
  "documents": [
    {
      "title": "Thyris UI Documentation",
      "path": "thyris-ui/index.md",
      "url": "https://docs.thyris.ai/docs/thyris-ui"
    }
  ]
}

An unrecognized section is valid and returns documentCount: 0 with an empty documents array. An unfiltered response can be large because it includes every document entry. Use a section filter whenever the complete inventory is unnecessary.

Choosing the Right Tool

User intent	Tool sequence
“What is Thyris and which problems does it solve?”	`resolve_docs_action`, then synthesize the answer
“Compare MCP and UCP for my use case.”	`resolve_docs_action` with use-case context, then synthesize the comparison
“Why is my catalog webhook returning 401?”	`resolve_docs_action`, optionally `get_document` for a truncated source, then troubleshoot
“Summarize Merchant Services for an executive.”	`resolve_docs_action`, then produce the requested summary format
“Inspect my app and create a Merchant integration roadmap.”	Inspect code, `research_docs`, `read_documents`, optionally `find_related_docs`, then synthesize
“Find the exact header used for webhook authentication.”	`search_docs`, then optionally `get_document`
“Read this specific API guide.”	`get_document`
“What pages exist under Thyris UI?”	`list_doc_sections` with `section: "thyris-ui"`
“How many published documents are there?”	`list_doc_sections` with no section
“Read these exact guides and combine them.”	`read_documents`

Do not use list_doc_sections as a substitute for search. It returns titles and paths but no document body or relevance ranking.

Tool Summary​

resolve_docs_action​

Input​

Output​

research_docs​

Input​

Output​

search_docs​

Input​

Output​

read_documents​

Input​

find_related_docs​

Input​

get_document​

Input​

Output​

Not-found error​

list_doc_sections​

Input​

Output​

Choosing the Right Tool​

Tool Summary

`resolve_docs_action`

Input

Output

`research_docs`

Input

Output

`search_docs`

Input

Output

`read_documents`

Input

`find_related_docs`

Input

`get_document`

Input

Output

Not-found error

`list_doc_sections`

Input

Output

Choosing the Right Tool