listBrains

List brains

List the brains you can see. A brain is a folder of documents about one thing (the business, a website), with a brain.md card that names its blueprint. Returns each brain's id, blueprint, level, readable parent and depth by ring. Then call getBrain with an id.

Arguments

Argument	Type	Required	Description
`project`	string	optional	Optional project id from listProjects, to list the brains in that project only

Scopes

knowledge:read

Annotations

Read only: yes
Destructive: no

When to use

Call listBrains to find out what Sasha knows about the business, a website or another subject, and how complete that knowledge is.

A brain is a folder inside a project that holds a brain.md card and a set of ordinary documents. The card names a blueprint, for example site@1: the plan for that kind of brain, with the full list of documents it should have. The card lists only its differences from the blueprint: documents it adds and documents it drops. See getBlueprint.

The tool needs the knowledge:read scope.

Without project, it looks in every project this person can see. With project, it looks in that project only.
id is <project>/<folder>. Pass it to getBrain or searchBrain as brain.
blueprint is the blueprint version the brain uses. A card that names a blueprint without a version (site) uses the latest one. type is the blueprint's id.
level is tenant for a brain in a member's own home, and sasha for a brain in a shared project.
parent is the parent brain's id only when this person can read it. Otherwise it is null.
depth has one entry for each ring that the brain's documents use, in ring order. The documents are the blueprint's, minus the ones the brain drops, plus the ones it adds. Each entry counts how many are filled (have text), checked (a person checked them), declined (the owner chose not to answer), outOfDate and missing. A document can be filled, checked and out of date at the same time.
newerBlueprint appears when a newer version of the brain's blueprint is available. getBrain says what it would change.
A card that names a blueprint this release does not have is listed with warnings and depth: null.
card is the card's path. Pass it to readDoc to read the card.
A card at the root of a project is not a brain. The tool looks at most 4 folders deep and reads at most 500 folders in each project. It returns at most 50 brains. When truncated is true, name a project.

A member sees the brains in their own home and in each shared project where they hold a grant. Admin and staff see the brains in every active shared project, but none in a member home.

Example

{ "project": "northwind-advisory" }

{
  "brains": [
    {
      "id": "northwind-advisory/brains/business",
      "type": "business",
      "title": "Northwind Advisory",
      "blueprint": "business@1",
      "level": "sasha",
      "parent": null,
      "card": "northwind-advisory/brains/business/brain.md",
      "depth": [
        { "ring": "Public Context", "stage": "Scope", "documents": 4, "filled": 2, "checked": 1, "declined": 0, "outOfDate": 0, "missing": 2 },
        { "ring": "Organisational Knowledge", "stage": "Land", "documents": 5, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 5 },
        { "ring": "Proprietary Methodology", "stage": "Expand", "documents": 6, "filled": 2, "checked": 1, "declined": 1, "outOfDate": 1, "missing": 3 },
        { "ring": "System Integration", "stage": "Embed", "documents": 3, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 3 },
        { "ring": "Flow", "stage": "Flow", "documents": 2, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 2 }
      ]
    },
    {
      "id": "northwind-advisory/brains/website",
      "type": "site",
      "title": "Northwind Advisory website",
      "blueprint": "site@1",
      "level": "sasha",
      "parent": "northwind-advisory/brains/business",
      "card": "northwind-advisory/brains/website/brain.md",
      "depth": [
        { "ring": "Public Context", "stage": "Scope", "documents": 10, "filled": 2, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 8 },
        { "ring": "System Integration", "stage": "Embed", "documents": 3, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 3 },
        { "ring": "Flow", "stage": "Flow", "documents": 1, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 1 }
      ]
    }
  ],
  "truncated": false
}

Refusals and what to do

Error in listBrains: Not found: the project you named does not exist, or this person cannot see it. Call listProjects and use an id from that list, or leave project out.
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 listBrains 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 brains list is not an error. It means that no folder this person can read holds a brain.md card.

getBrain shows one brain's contents page.
getBlueprint lists the blueprints and their documents.
searchBrain searches inside one brain.
listProjects gives the project ids.
getDocs explains brains in its brains section.