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

Goes well beyond the annotations: it discloses network fetching for URLs, that raw/ is immutable, that a repeat submission is idempotent and returns 'status: exists' without writing, and that a `note` flags thin JS-only or paywalled captures with a recommended retry path. Those are exactly the behavioral traits (side effects, retry semantics, partial-failure signaling) annotations cannot convey.

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?

Front-loaded with the core action and scope in the first sentence, then capability, then exclusion, then behavioral caveats — a sensible order with no filler. It is on the dense side for a description, but nearly every clause carries decision-relevant 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?

An output schema exists, so return shapes need not be spelled out, and the description still covers the one return value an agent must branch on ('status: exists'). For a 5-param write tool with openWorld behavior, nothing needed to call 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%, so the field meanings are already documented; the description still adds real semantics by explaining the interplay between `source` and `text` ('call again with `text`' when a capture is thin) and that supplying the body skips fetching. That is useful beyond the per-field descriptions, though it does not cover `published`/`author` overrides explicitly.

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 destination ('Capture an external source into the agent's immutable raw/ folder as a dated markdown file') plus the provenance fields written. It also explicitly separates itself from brain_remember for short facts, so an agent can distinguish it from siblings 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?

Enumerates the supported input kinds (web page, GitHub README, YouTube subtitles, PDF bytes, local file, pasted text) and gives an explicit exclusion ('Not for short facts (brain_remember)'). It also positions the tool as step 1 of /distill and states what the caller must do afterward, which removes ambiguity about the follow-up workflow.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses deduplication, relevance+recency ranking, a ~6k token cap, and that partial results are normal with a `stores` field naming unreachable stores rather than failing. It also explains the `⚠ Fact changed` supersession ranking rule, which is non-obvious behavior an agent must interpret correctly.

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?

Front-loaded with the core verb and scope, then usage guidance, then behavioral caveats — a clear three-part structure with no filler sentences. It is somewhat dense and long, but nearly every clause carries actionable 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 multi-store search with a full output schema, the description covers everything an agent needs to call and interpret it: scope semantics, ranking/cap, partial-failure behavior, supersession banners, and sibling routing. Return-value detail is correctly delegated to the output schema.

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 the baseline is 3; the description adds real meaning on top by explaining that scope='transcript' searches only what past sessions said and ran, and by framing results as a single deduplicated list. It does not re-explain limit/format, but the schema already does that well.

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?

Opens with a specific verb+resource ('Search the agent's long-term memory') and enumerates exactly what content kinds and backends are covered (SQLite, markdown vault, Hindsight, graph), plus the ranking/dedup/cap behavior. An agent can immediately tell this apart from brain_remember and brain_status without inspecting the 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?

Explicit when-to-use ('before answering anything about past sessions, earlier decisions or the user's preferences, and before brain_remember to avoid writing a duplicate') and explicit when-not ('Not for health checks (brain_status) and not for reading a file you already know the path of'), naming the sibling to route to.

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?

Goes well beyond the annotations: it discloses that nothing is ever deleted, that a near-duplicate returns status duplicate with the existing entry and writes nothing, that changed values are appended under a '⚠ Fact changed' banner with the old line preserved and reported as a contradiction, and that secrets are refused. It also explains the per-store `layers` report (written|exists|pending|failed|refused), which makes partial-failure behavior legible. Only auth/permission requirements are left unstated, keeping it just off 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?

Three tight paragraphs ordered by importance: what it does, when to use it, then the behavioral contract. The multi-line formatting is slightly denser than necessary and the store enumeration could be a single clause, but every sentence carries information an agent needs.

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 7-parameter multi-store write with an output schema present, the description covers the missing pieces: mutation semantics, duplicate/contradiction handling, partial-failure visibility, and safety refusals. An agent has enough to call it correctly and interpret the outcome without further context.

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%, so `kind`, `text`, `extra`, `force`, `domain`, `source` and `mission` are already documented in the schema, and the description does not add new syntax or format detail for them. It only implicitly reinforces `kind` values by naming fact/decision/correction/preference/relationship in the usage sentence and by pairing the duplicate behavior with `force`. Baseline 3 is appropriate when the schema carries the load.

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 ('Write one memory item to every store in one call') and enumerates the target stores in write order (markdown vault, SQLite, Hindsight, entity graph). It explicitly names the two siblings it is not (brain_distill for documents, brain_session for summaries), so an agent can route 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?

Gives a concrete trigger ('the moment the user states a fact, decision, correction, preference or relationship worth keeping across sessions'), a cardinality rule ('one call per item'), and explicit exclusions mapped to the correct alternatives. Nothing about when-to-use is left to inference.

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 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.

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.

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.

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.

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.

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.

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, but the description adds meaningful semantics: what each health check covers, when `ok` is false, and that `stores` names the failing store. This goes well beyond the annotation surface and clarifies the output's operational meaning.

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?

The description is dense but well organized: the first sentence front-loads the full scope, the second gives usage guidance, and the third explains the `ok`/`stores` semantics. Every sentence contributes to correct invocation or interpretation.

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 parameters, full annotation coverage, an output schema, and sibling tools, the description supplies everything an agent needs: what is inspected, when to call it, how to interpret `ok` and `stores`, and what it is not (a search).

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 there is nothing for the description to disambiguate. The baseline for a parameterless tool applies, and the description correctly does not invent parameter details.

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 opens with a specific verb and resource ('Report the agent's health') and enumerates the exact checks performed across vault, SQLite, Hindsight, graph, wiki lint, context size, session ids, decisions, and traits. It also explicitly distinguishes the tool from brain_recall by stating 'Not a search'.

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 gives clear triggers: when a store seems down, before maintenance, or when the user asks how memory is doing. It also names the closest alternative (brain_recall) and excludes search use, so an agent can route correctly.

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