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

With no annotations, the description carries the full behavioral burden. It does disclose two non-obvious behaviors not in the schema: a required body convention (opening blockquote addressed to the next agent) and a cortex-reuse policy. It says nothing about what happens on duplicate or near-duplicate entries, whether confidence is caller-asserted or validated, or what a failed cortex reference does.

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 imperative lines, zero filler, with the core action stated first and the formatting convention immediately after. Every sentence constrains agent behavior.

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 and no annotations, so the description is the only source of behavioral context for a 7-parameter mutation tool. The encoding ritual is well covered, but return values, error behavior, and the valid domain of type/confidence are all absent — an agent can call it, but cannot predict what comes back.

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 0% across 7 parameters, so the description must compensate and largely does not. It adds genuine meaning for only two — body (required blockquote opener) and cortex (reuse vs. create, cross-referencing brain_list). The type, confidence, tags, description and title parameters get no semantic treatment at all; notably 'type' defaults to 'fact' with no hint of what other values are legal.

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 — 'Store one durable learning' — and enumerates the content kinds it accepts (a fix that worked, a constraint, a preference, a decision). That makes it clearly the write path among siblings (brain_list, brain_search, brain_read are all reads). It doesn't explicitly name a write-side sibling such as brain_supersede to contrast against, so it falls short of 5.

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 real procedural guidance: begin the body with a 2-3 sentence blockquote for the next agent, prefer an existing cortex and consult brain_list, and create a new cortex only for a new theme. It names a sibling and the condition triggering it. Missing is the negative case — when to use brain_supersede or brain_link instead of encoding a new entry.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that linking is bidirectional, which is useful, but says nothing about permissions, whether existing links are overwritten, what happens if either note does not exist, or how the `rel` relationship behaves.

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 two short sentences with no waste, and the core action is front-loaded. Even the second sentence is brief enough not to undermine clarity.

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 mutation tool with no annotations and 0% schema description coverage, this is not complete enough. The output schema means return values need not be explained, but the description still omits key details about `rel`, link conflicts, and error behavior that an agent needs before invoking the tool.

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 0%, so the description should explain the parameters. It implies that `a` and `b` are the two notes, but it never mentions `rel`, its default value, or what relationship values are meaningful. The description adds little beyond a vague mapping to two of the three parameters.

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 states a specific verb and resource: "Link two notes both ways." That is clear and actionable. It does not explicitly differentiate from siblings such as brain_encode or brain_supersede, but its purpose is still distinct.

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 only guidance is a value heuristic: "Links across cortices are the most valuable." There is no explanation of when to use this tool versus a plain note update, when not to use it, or what prerequisites or failure conditions exist.

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?

No annotations are provided, so the description carries the burden. It discloses that cortices are returned with note counts and that one cortex returns notes, but it does not mention pagination, ordering, permissions, or failure behavior.

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 front-loaded sentence with no wasted words. The primary operation and conditional variant are both stated 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 simple list tool with no output schema and no annotations, the description covers the two core modes and what is returned at a high level. It remains incomplete regarding return structure, ordering, pagination, and parameter details.

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 0%, so the description must clarify the optional cortex parameter. It does explain the conditional behavior: one cortex means notes of that cortex, otherwise list cortices with counts. However, it does not specify the parameter name, format, matching rules, or behavior for invalid values.

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?

Uses a specific verb (“List”) and names the resources (“cortices” and “notes”), making the tool's purpose clear. It does not explicitly distinguish itself from siblings like brain_search or brain_read, so a 4 rather than 5.

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 implies two basic modes—omit cortex to list cortices, provide cortex to list notes—but does not say when to use this tool instead of brain_search, brain_read, or other siblings. No exclusions or prerequisites are 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?

With no annotations, the description carries the full burden. It does disclose the return format (full Markdown plus frontmatter), which is genuinely useful behavior context, but says nothing about read-only semantics, error behavior for a missing id, or any permission constraints. The output schema covers return shape, lowering the bar somewhat.

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 key output detail front-loaded; every word earns its place and nothing is redundant.

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?

A simple one-parameter read tool with an output schema, so the description needn't explain return values. What is missing is minor but real: the identifier format and behavior when the note does not exist.

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 single required parameter 'id' has 0% schema description coverage, and the description does not compensate by explaining what the id is (slug, UUID, path?) or where an agent obtains it. With only one parameter this is a small gap, but it is entirely undocumented.

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 ('Return') and resource ('the full Markdown of one note') with a scope qualifier ('frontmatter included'). The phrase 'one note' implicitly distinguishes it from brain_list and brain_search, though no sibling is named 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 implied: fetch a single note's content, as opposed to listing or searching via brain_list/brain_search. However, there is no explicit when-to-use/when-not guidance or mention of prerequisites such as needing to know the note id first.

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?

With no annotations provided, the description carries the full behavioral burden. It discloses the return fields and recommends a follow-up read, but it does not clarify read-only safety, permission requirements, rate limits, or the behavior of optional parameters such as include_superseded.

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 three short sentences with no wasted language, and the core instruction is front-loaded. Return fields and the recommended next action are packed efficiently into the remaining text.

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?

The output schema exists, so return-value documentation is not strictly required, though the description mentions fields helpfully. However, for a search tool with four parameters and no annotations, the description should explain optional filters like cortex and include_superseded to support correct invocation.

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 0% for four parameters, and the description does not name or explain query, k, cortex, or include_superseded. The phrase 'relevant to a task' loosely implies a query concept but provides no real parameter semantics, leaving three optional parameters completely undocumented.

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 clearly states a specific action and resource: recall notes relevant to a task. It also distinguishes the tool from brain_read by telling the agent to open promising results with brain_read.

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 explicit usage guidance: call this before any non-trivial step, and use brain_read for promising results. It does not explain when not to use it or how it relates to siblings like brain_list or brain_encode, but the primary usage context is clear.

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?

With no annotations, the description carries the full burden. It discloses that the operation retires an old note and preserves history, but it does not explain reversibility, permissions, what happens to the old note or links, or other side effects of this mutation.

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 short sentences, front-loaded with the core action, and no wasted wording. The behavioral rule is compact and relevant.

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?

Although an output schema exists, this is a mutation tool with no annotations and 0% schema description coverage. The description does not explain the required 'reason' parameter, what 'retire' actually does, or the side effects, leaving an agent under-informed.

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 0%, so the description must compensate. It only loosely distinguishes 'old' and 'new' as notes and entirely omits the required 'reason' parameter and accepted identifier formats.

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 uses a specific verb ('Retire') and resource ('outdated note') and clarifies the relationship to a newer note. It does not explicitly differentiate itself from siblings such as brain_encode or brain_read, so it falls short of a 5.

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 implies the tool should be used when a note is outdated and a newer one exists, and adds the rule 'Never edit history in place.' However, it does not name alternatives or explicitly state when not to use this tool versus brain_encode or brain_read.

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?

With no annotations at all, the description carries the full behavioral burden. It does disclose the core state change (a 're-checked today' marker, i.e. an implicit timestamp stamp) and that confidence is optional, but it omits whether a supplied confidence overwrites the prior value, what happens if the id doesn't exist, and whether validation affects search ranking/decay.

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 front-loaded sentence with zero filler; the primary action comes first and the optional modifier follows.

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 simple 2-param tool with an output schema (so return values need no explanation) this is close, but the missing confidence scale and unstated error/side-effect behavior leave gaps the agent can't fill from structured fields, since no annotations and no param descriptions exist.

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 0%, so the description must compensate for both params. It does map 'note' to id and 'optionally with a new confidence' to confidence, clarifying optionality — but it gives no scale, bounds, or units for confidence (the schema allows any number), which is the one piece an agent most needs.

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: marking a note as re-checked, with an optional confidence update. The action is distinguishable from brain_encode/brain_link/brain_supersede in kind, though the description never names those siblings to draw the contrast 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?

The description gives no when-to-use condition beyond the implied re-validation workflow, and no guidance on the key decision an agent faces: validate vs. supersede when a note is out of date, or validate vs. encode when it should be re-created. No prerequisites or exclusions are stated.

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