Sasha MCP reference

searchBrain

Search inside a brain

Search the documents of one brain (case-insensitive text match), and with includeParents its readable parent brains too. Returns the brain, document title, path, line and snippet for each match. Read the full document with readDoc and that path.

Arguments

Scopes

knowledge:read

Annotations

• Read only: yes
• Destructive: no

When to use

Use searchBrain when the question is about one subject that has a brain, for example "what does the website say about discounts?". Then read the full document with readDoc.

The tool needs the knowledge:read scope.

• brain is a brain id from listBrains: <project>/<folder>.
• The search covers the files in the brain's folder and its sub-folders. A sub-folder that holds its own brain.md is another brain and is not searched.
• With includeParents: true, it also searches the parent brain, and that brain's parent, up to 3 levels, but only the ones this person can read. searched lists the brains it covered, in order.
• The matching is the same as searchKnowledge: a plain, case-insensitive text match, not a semantic search. query must have at least 2 characters. It returns one result for each file (the first line that matches), at most 40 results in all, and skips files larger than 2 MB.
• Each result has the brain it came from, the document title (the title in the brain's list, for a listed document), the path, the line and a snippet. Pass path to readDoc as it is, with no project.

Example

{ "brain": "northwind-advisory/brains/website", "query": "discount", "includeParents": true }

{
  "brain": "northwind-advisory/brains/website",
  "query": "discount",
  "searched": [
    "northwind-advisory/brains/website",
    "northwind-advisory/brains/business"
  ],
  "results": [
    {
      "brain": "northwind-advisory/brains/website",
      "path": "northwind-advisory/brains/website/offer.md",
      "document": "Offer",
      "line": 4,
      "snippet": "Strategy review: from 4,500 GBP. A discount above 5 per cent needs a partner's approval."
    },
    {
      "brain": "northwind-advisory/brains/business",
      "path": "northwind-advisory/brains/business/commercial-logic.md",
      "document": "Commercial logic",
      "line": 2,
      "snippet": "summary: Day rates, the 10 per cent maximum discount and walk-away terms."
    }
  ],
  "truncated": false
}

When truncated is true, the search stopped at 40 results. Make the query narrower, or leave out includeParents.

Refusals and what to do

• Error in searchBrain: Not found: there is no brain with this id that this person can read. The answer is the same whether the brain is hidden or does not exist. Call listBrains and use an id from that list.
• A query shorter than 2 characters is refused as invalid arguments.
• If the connection does not hold knowledge:read, the tool is not in your tool list, and a call to it returns MCP error -32602: Tool searchBrain not found. Read the permissions section of getDocs. A scope is never added to an existing connection: the person must reconnect, or mint a new token, with knowledge:read.
• An empty results list is not an error. Try other words, or use searchKnowledge to search every project.

Related

• getBrain shows the brain's contents page.
• listBrains gives the brain ids.
• readDoc reads a document that the search found.
• searchKnowledge searches every visible project, not one brain.
• getDocs has a limits section with the search limits.