brain-core

Overview Schema Source Related Servers Discussions Admin

brain_session

Destructive

Open or close an agent's working session: start loads context, brief, executive state and recovery; end archives the session, updates state and syncs cross-agent notes.

Instructions

Open or close the agent's working session. Call phase='start' once at the beginning of every conversation, before any other brain tool; call phase='end' once when the user signals they are done. Not for single facts (brain_remember).

    start returns the whole context block: the cron daily brief with a stale flag,
    executive state (objective, missions, pending decisions), the configured Hindsight
    mental models, a recall per top mission, the staged-inbox count, and `recovery` when
    the previous session never closed.

    end drains the Hindsight queue, appends a close line to today's session archive,
    replaces executive_state, session_critique and the cross-agent sync file with the
    bodies you pass (or a stub built from this session's brain_remember calls), reports
    which trait signals moved, and writes the clean-close marker. A second end overwrites
    the first.

Input Schema

Name	Required	Description
`sync`	No	end only: full markdown body of the cross-agent sync note.
`phase`	Yes	'start' or 'end'.
`critique`	No	end only: full markdown body that replaces session_critique.
`session_id`	No	Caller's session id; omit to keep the one the server opened.
`executive_state`	No	end only: full markdown body that replaces executive_state.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.2.6Nov 2, 2026

addedInput schema / properties / critique / description

Added value: +"end only: full markdown body that replaces session_critique."

addedInput schema / properties / executive_state / description

Added value: +"end only: full markdown body that replaces executive_state."

addedInput schema / properties / phase / description
```
Added value: +"'start' or 'end'."
```

addedInput schema / properties / session_id / description

Added value: +"Caller's session id; omit to keep the one the server opened."

addedInput schema / properties / sync / description

Added value: +"end only: full markdown body of the cross-agent sync note."

First observedv0.1.0Nov 2, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and idempotentHint=false; the description supplies the specifics behind those flags — which stored artifacts get replaced (executive_state, session_critique, cross-agent sync file), the stub fallback, and that a second end overwrites the first. Start's payload plus the `recovery` flag for an unclosed prior session is also disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the call rules, then split into start-return and end-effect paragraphs, each sentence carrying distinct information. It is dense and longer than most definitions, but no sentence is filler; the return-value detail is arguably redundant given an output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent session lifecycle tool with five params, the description covers timing, prerequisite ordering, mutation targets, fallback behavior, and re-invocation semantics. An output schema exists, yet the extra explanation of start's context block only reinforces the contract.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so per-parameter descriptions already carry the baseline. The description goes further by explaining that the body parameters replace stored documents and that omitting them triggers a stub assembled from this session's brain_remember calls — behavior the schema never states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair and resource — opening or closing the agent's working session — and enumerates the two phase values inline. It also contrasts itself with brain_remember ('Not for single facts'), so an agent can separate it from siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit invocation rules: phase='start' once at the beginning of every conversation before any other brain tool, phase='end' once when the user signals they are done. It also names the exclusion (single facts) and routes that case to brain_remember.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server