Brain Memory

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

Annotations already flag this as a mutating, destructive operation, and the description adds real context beyond that: the memory is moved to _archived/ and the action is recoverable rather than a permanent delete. That is exactly the kind of disclosure that tempers the destructiveHint, though it does not say whether the id must exist or what happens if it doesn't. The description softens but does not contradict the destructive annotation, so no contradiction flag.

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

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

One sentence, action and effect front-loaded, with the important recoverability caveat in a tight parenthetical. Nothing is padded and nothing essential is trimmed.

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

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

For a one-parameter, no-output-schema tool with annotations covering the safety profile, the description supplies everything needed to call it correctly: the argument, the effect, and reversibility. The only omission is how archived memories are restored or which tool does that, which is minor here.

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

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

Schema description coverage is 100% and the single parameter already documents itself as 'Memory id to archive'. The description only restates 'by `id`' and adds no format, source, or lookup guidance, so the baseline 3 applies.

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

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

States a specific verb (archive) on a specific resource (a memory) and names the effect (stops surfacing in recall). It is unambiguous against siblings like brain_recall or brain_pin without opening any schema.

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

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

The phrase 'so it stops surfacing in recall' clearly conveys the context in which an agent would pick this tool, and the recoverability note signals it is the non-permanent option. It stops short of naming when-not-to-use conditions or pointing to a restore/unpin alternative, so no explicit exclusion is given.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive profile is covered. The description adds that exactly the input text is stored (no auto-inference) and that it returns id and path, but it omits the side effects the destructive hint implies — e.g. supersede closing prior memories' validity windows and some origins being held for verification.

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

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

Two tight sentences, front-loaded with the action and the return value. Minor redundancy between 'containing exactly the text provided in `content`' and 'Only that text is stored', but nothing wasteful.

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

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

For a 9-parameter tool with nested objects (authorized_by), enums and a verification workflow, the description is thin: it never mentions when a write is held for verification, how origin affects recall, or the pin/verify follow-ups. The rich schema and the stated return value (id, path) compensate enough to keep it at minimum viable.

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

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

Schema description coverage is 100% and the nine parameters (supersedes, origin, authorized_by, valid_from/until) are richly documented in the schema itself, so baseline 3 applies. The description only reinforces the meaning of `content` ('exactly the text provided', 'Only that text is stored'), adding little beyond the schema.

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

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

Specific verb+resource ('Store a new memory') with a scope qualifier that distinguishes it from the read-side sibling brain_recall, and it names the content categories it accepts. It stops short of explicitly contrasting with siblings like brain_pin or brain_verify, but the operation is unmistakable.

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

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

The description never says when to memorize versus not, and does not mention any alternative or follow-up tool in the sibling set (brain_pin, brain_verify). Usage is only inferable from the verb itself; no exclusions or prerequisites are stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds meaningful behavioral context beyond that: pinning promotes the memory to a permanent tier that is always loaded and never decays. It does not explain the cost/irreversibility angle that 'destructive' implies, which keeps it from a 5.

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

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

One tight sentence with the action front-loaded and the consequence trailing. No filler, no redundancy, nothing that could be cut without losing information.

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

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

For a single-parameter tool with annotations covering idempotency and destructiveness and no output schema, the description supplies the essential effect an agent needs. The only omission is explicit guidance that brain_unpin reverses this, which would complete the lifecycle story.

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

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

Only one parameter (id) and schema coverage is 100%, including an example format in the schema itself. The description's 'by `id`' adds nothing beyond the schema, so the baseline 3 for a fully documented single parameter is appropriate.

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

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

Specific verb (pin) plus resource (memory) plus the concrete mechanism: moving it to the 'always-present tier' so it 'loads every session and never decays.' That effect statement cleanly separates it from siblings like brain_forget, brain_recall, and brain_unpin without the agent needing to open any schema.

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

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

It conveys when this tool is appropriate ('so it loads every session and never decays'), which is real usage context rather than mere restatement. It stops short of naming the inverse operation (brain_unpin) as the way to undo a pin, so the agent gets clear context but no explicit alternative routing.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description isn't carrying the safety burden. It adds some behavioral context by revealing that results are heuristically ranked (relevance + decay + activation + context match), implying the list is not exhaustive, but the parenthetical formula is more trivia than actionable guidance and nothing is said about result ordering guarantees or superseded-fact handling.

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

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

A single sentence that front-loads the verb and resource before the ranking detail. The parenthetical scoring formula is the only somewhat expendable element, but it is brief and does not bury the primary information.

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

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

For a recall tool with no output schema, the description should give at least a hint of what a returned memory looks like; it instead stops at ranking. The rich input schema and readOnlyHint cover the calling side, but the response side is left entirely unspecified.

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

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

Schema description coverage is 100% with five well-documented parameters, including the subtle as_of/as_known_of time-travel semantics, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what the schema already provides, which is the baseline-3 case.

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

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

States a specific verb (recall) and resource (the user's stored memories) plus the scope of relevance ranking, so the operation is unambiguous. It does not explicitly contrast itself with siblings like brain_verify or brain_status, but the verb+resource pair is concrete enough that sibling names alone disambiguate.

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

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

The description never says when to reach for this tool versus brain_verify, brain_status, or brain_memorize, nor does it state any preconditions. Usage is only inferable from the purpose statement, and no alternatives or exclusions are named.

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

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

Annotations only declare readOnlyHint=true, so the description carries the burden of describing the payload, and it does so concretely: memory count, last-updated timestamp, and the brain list with the in-use brain marked active. It does not mention cost, latency, or whether the status is computed live versus cached, which keeps it short of a 5.

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

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

A single sentence that front-loads the purpose ('Health overview of the user's brain') and then lists the returned fields. No filler, no repetition of the title.

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

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

With no output schema, the description must convey return contents and it largely does, covering all three reported items. It stops short of describing the shape or units (e.g., timestamp format, whether counts are per-brain or global).

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate beyond the fact that no scope or identifier is required.

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

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

The description names a specific resource (the user's brain) and enumerates exactly what is reported: memory count, last-updated time, and the account's brains with the active one marked. It is clearly a read/status tool, distinguishable from the mutation-oriented siblings (brain_memorize, brain_forget, brain_pin, brain_use), though it never names an alternative explicitly.

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

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

Usage is only implied by the phrase 'health overview' – an agent can infer this is for inspection rather than recall or mutation, but there is no explicit when-to-use statement or condition that selects this tool over brain_recall or brain_verify.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered. The description adds genuinely new behavioral context: the memory is not deleted but demoted back to normal recall and decay, which materially changes how an agent should reason about the side effect.

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

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

A single sentence with no waste; the action and its effect are front-loaded and the parenthetical explains the consequence immediately.

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

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

For a one-parameter toggle with no output schema and annotations covering safety and idempotency, the description supplies the key missing piece (the resulting state of the memory). It is nearly complete, though it does not state error behavior for an unknown or already-unpinned id.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents 'id' fully. The description's 'by id' phrasing adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (remove/unpin) and resource (a memory, by id, from the always-present tier). It is clearly the inverse of brain_pin, but the sibling is never named, so differentiation is inferred rather than stated.

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

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

The parenthetical 'returns it to normal recall + decay' implies the situation in which you'd want this (when a memory should no longer be always-present), but there is no explicit when-to-use, when-not-to-use, or named alternative versus brain_forget or brain_pin.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds genuinely new behavioral context: the selection persists across later sessions, and no data is copied between brains — the latter pre-empts a plausible mistaken expectation about a write-labeled tool.

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

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

Three short sentences, action front-loaded, each carrying distinct information (what changes, how to enumerate, persistence, no data movement). No filler.

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

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

No output schema exists, and the description plus annotations cover the mutation target, persistence, and scope of side effects. Minor gaps remain around failure handling for an unknown brain name, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100% and the single parameter already documents 'Name (case-insensitive) or id of the brain to use'. The description's 'by name or id' restates that, adding no syntax or matching detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Switch which ... brains this connector reads and writes') with the selector format (name or id). It is clearly distinguishable from siblings like brain_memorize/brain_recall and points at brain_status for enumeration.

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

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

Implies the use case (change the active brain for this connector) and names the companion tool for listing available brains. It does not state exclusions or error behavior when the named brain doesn't exist, so it stops short of explicit when-not guidance.

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

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

Adds real value beyond the blanket annotations: it discloses that 'list' is read-only, 'approve' clears the flag while preserving origin and trust weighting, and 'reject' archives the memory. This mode-level detail is not derivable from destructiveHint=true/readOnlyHint=false alone.

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

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

Two tight sentences: the quarantine rationale first, then the per-action behavior. No filler and the default action is noted inline.

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

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

No output schema exists, but the description focuses on behavior rather than return shape, which is appropriate. It leaves implicit that ids are required for approve/reject and does not describe what 'list' returns.

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

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

Schema coverage is 100%, so baseline is 3, but the description spells out what each enum value of 'action' actually does, adding meaning beyond the schema's terse 'What to do'. The 'ids' parameter still relies entirely on the schema.

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

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

States a specific verb+resource (review/resolve memories pending verification) and immediately explains the quarantine mechanism that defines the resource. It is clearly distinguishable from siblings like brain_recall or brain_forget.

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

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

Explains the three actions and their semantics, which implicitly tells the agent which mode to pick. It does not explicitly name sibling tools or state when a review workflow should be preferred over brain_recall, but the workflow context is clear.

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