Find a fact and cite its source

The job

Answer a question from the organisation's own documents, and tell the person which document each fact comes from.

Prerequisites

The connection holds knowledge:read. Admin, staff and member connections can all hold it.
A member finds documents only in their own member home and in the shared projects where they hold a grant. Admin and staff find documents in every active shared project, but in no member home. See listProjects.
No instance switch is needed.

Steps

The example question is: "What is the maximum discount that Northwind Advisory can give?"

List the projects that this connection can see.
```
{}
```
Keep the id of each project. If the question names a subject that belongs to one project, use that id as project in the next step. An empty projects list means that this person can see no project.

Search for the subject.

{ "query": "maximum discount", "project": "northwind-advisory" }

{
  "query": "maximum discount",
  "results": [
    { "path": "northwind-advisory/2026-q2-pricing-review.md", "line": 20, "snippet": "2. The maximum discount stays at 10 per cent. Partners asked that every discount above 5 per cent is recorded in the proposal log with its reason." },
    { "path": "northwind-advisory/meetings/meeting-2026-08-14-pricing.md", "line": 9, "snippet": "Discussion: the commercial lead said the pricing policy sets the maximum discount at 10 per cent. Two partners said that the volume of work justifies more. One partner said a larger discount would set a precedent for other public-sector clients." },
    { "path": "northwind-advisory/pricing-policy.md", "line": 24, "snippet": "The maximum discount is 10 per cent of the fee. A discount needs a partner's approval. We give a discount only for one of these reasons:" }
  ],
  "truncated": false
}

Each result has a path, a line and a snippet. The result for northwind-advisory/pricing-policy.md is the best source here, because a policy is the document that sets the rule.

The search is a plain text match, not a semantic search. If it finds nothing, try other words before you tell the person that the subject is not documented. If truncated is true, make the query narrower or name a project.

Read the document. A snippet is one line, so do not state a fact from the snippet alone. Pass the path from the search as it is, with no project.
```
{ "path": "northwind-advisory/pricing-policy.md" }
```
If truncated is true, call readDoc again with offset set to nextOffset, and join the pages in order. If the first page returned a version, pass it on each next page as version, so that the read fails if the document changes between pages. See readDoc for the paging rules.
Give the answer. State the fact as the document states it, and give the source path, for example: "The maximum discount is 10 per cent of the fee, and it needs a partner's approval (northwind-advisory/pricing-policy.md, line 24)." The line number comes from searchKnowledge. It is the first line in the file that matches the query.
Check the other results, and read any that could change the answer. In this example, northwind-advisory/2026-q2-pricing-review.md (line 20) says that the maximum stays at 10 per cent, so it agrees with the policy. northwind-advisory/meetings/meeting-2026-08-14-pricing.md (line 9) records a discussion about a larger discount. A meeting note records what people said. It does not change the policy. If a result says something different from your source, tell the person, and give both paths.

To see every document in a project instead of searching, call listDocs. Its paths have no project prefix, so pass them to readDoc with the same project.

What can go wrong

Error in searchKnowledge: Not found or Error in readDoc: Not found: the project does not exist, or this person cannot see it. Use a project id from listProjects.
Error in readDoc: Document not found: the project is visible, but the document is not there. Check the path with listDocs or searchKnowledge.
Error in readDoc: version_conflict:stale_version: the document changed between pages. Read it again from offset 0 without version.
A query shorter than 2 characters is refused as invalid arguments.
MCP error -32602: Tool searchKnowledge not found: the connection does not hold knowledge:read. Read the permissions section of getDocs. Do not tell the person that Sasha cannot search.

Find a fact and cite its source

The job

Prerequisites

Steps

What can go wrong

Related notes