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

Adds real behavior beyond the annotations: a contradicting or restating memory replaces the older one, and the older version stays in history. That supersession-and-versioning rule is exactly the kind of non-obvious effect an agent needs. Size limits are also restated, and nothing contradicts the non-destructive hint.

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 sentences, front-loaded with the trigger, then content shape, then supersession semantics. Slight redundancy in restating the ~800-word / Markdown guidance that the content schema already carries.

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 output schema, the description covers the write's side effects well but omits how to obtain the required brain id (the list_brains sibling) and how to choose kind, category, confidence, or entityType. Those gaps are significant for a 6-parameter create.

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 only 33% across 6 params. The description covers 'content' (already described in the schema) and says nothing about brain, kind, category, confidence, or entityType — four of which are undocumented in the schema as well. It leaves the agent guessing where the brain id comes from and how to set metadata.

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 ('Save a new Brain memory') and implicitly distinguishes itself from update_memory and delete_memory by the word 'new'. An agent can tell immediately this is the creation path.

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 an explicit trigger condition ('when the user explicitly asks to remember, save, or store something') plus a scoping rule (one memory per coherent fact, don't paste a long document). It does not name update_memory or search_brain as alternatives, so the when-not is only implied.

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 the bar is lower, yet the description goes further by disclosing that this is a reversible removal: the memory disappears from search and reads while "every saved version is kept," plus the concrete restore command. This is exactly the post-destructive recovery context an agent needs to reassure a user.

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 sentences, zero waste. The precondition is front-loaded and the recovery mechanism follows as supporting context; nothing is repeated from the title or schema.

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 two-param mutation with no output schema, the description covers the critical unknowns: reversibility, visibility impact, and the restore path. The one gap is that memoryId's meaning and how to obtain it is left entirely to the schema, which does not describe it.

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 only 50%: `brain` is documented (personal brain is "personal") but `memoryId` carries no description in either the schema or the prose. The description never mentions any parameter, so it does not compensate for the undocumented id.

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?

"Delete a Brain memory" names a specific verb and resource, and the description immediately qualifies the semantics as a soft delete where the memory "leaves search and reads" but versions persist. That is distinguishable from siblings like update_memory or get_memory_versions 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 trigger condition is explicit and restrictive: only "when the user explicitly asks to remove a saved fact." That implicitly excludes correction-style edits (which belong to update_memory), but no sibling tool is named as the alternative the way a 5 would require.

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/idempotentHint/destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the shape and size bound of the payload and the presence of addedBy and versionCount fields, and it flags a follow-up call. It does not mention behavior on a missing/invalid id (error vs empty), which is the main remaining gap.

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, zero filler; the identity of the tool and its scope lead, then payload characteristics, then the conditional escalation to get_memory_versions. Every sentence carries distinct 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?

With no output schema, the description does a reasonable job sketching the return shape (content, addedBy, versionCount) and the size limit, which is what an agent needs to decide whether to call it. Missing only id-format guidance and error/not-found behavior for full completeness.

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 50%: 'brain' is documented in the schema (including the "personal" default), but 'memoryId' has no schema description at all. The description only says 'by id' and adds nothing about id format or where to obtain it, so it does not compensate for the undocumented parameter. Baseline 3 is the correct ceiling here.

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 ('Fetch one Brain memory by id') and immediately characterizes what the returned content is (a fact or a Markdown mini-doc up to ~800 words). An agent can distinguish this from search_brain and list_brains 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 an explicit conditional branch: 'When versionCount is greater than 1, call get_memory_versions to read every saved revision.' That is a genuinely useful routing rule to a named sibling. It does not state when *not* to use this tool (e.g. when you only have a query and not an id, use search_brain), so it falls short of full 5-level 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?

Annotations already declare this is a safe read operation (readOnlyHint, idempotentHint, non-destructive), so the description does not need to repeat that. It adds real context beyond the annotations: result ordering (newest first), that each version carries full content, and that the current:true entry duplicates what get_memory returns.

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?

Four short sentences, with the core action, the ordering, the usage trigger, and the get_memory equivalence all front-loaded. Nothing is redundant or padded.

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 does explain the return shape well: version list, newest-first, full content per version, and the current:true marker. It does not mention whether history is truncated or paginated for long-lived memories, a minor but real omission for a version-history 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 coverage is only 50%: the 'brain' parameter is documented in the schema, but 'memoryId' has no description anywhere. The description implies that memoryId identifies 'one Brain memory' but does not explain how to obtain it (for example, from get_memory or search_brain). It therefore does not fully compensate for the gap, so the baseline score of 3 is correct.

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 ('Fetch every saved version of one Brain memory'), adds ordering ('newest first'), and explicitly separates it from the sibling get_memory, which returns only the current state. An agent can distinguish it from search_brain and get_memory without opening a 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?

'Use this when you need to see how a fact changed' gives a clear use condition, and the closing sentence about current: true routes agents to get_memory for the current-state case. There is no explicit 'do not use when' statement, so it falls just short of a 5.

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, closed-world and non-destructive, so the safety profile is covered. The description adds context annotations can't express: results are limited to brains visible to the current connection, and memories are not returned. It doesn't say anything about ordering or result size, but the tool is trivial enough that this is a minor gap.

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, front-loaded with the action and scope, then the required call ordering, then the disambiguation. Every sentence carries distinct information with 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?

For a zero-parameter, read-only listing tool with full annotation coverage, the description covers purpose, sequencing, and scope exclusions. Since there is no output schema, it could say slightly more about what a brain entry contains (e.g., id and name), but the mention of retrieving a brain id largely fills that role.

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 of 4 applies. There is nothing parameter-related the description could clarify, and it doesn't waste words pretending otherwise.

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 ("List Make0 brains") and scopes it to "this connection can use". The final sentence explicitly excludes memories, which is exactly the confusion risk given the sibling memory tools.

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?

"Call this first to get a brain id for search_brain" gives an explicit ordering and names the dependent sibling. The agent knows both when to use it and what to use the result for, with no inference required.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the retrieval pipeline (semantic + BM25, MiniLM cross-encoder rerank, two-hop related_to expansion), the fields attached to each result (addedBy, versionCount, truncated), and the truncation behavior. That is exactly the kind of operational context an agent needs to interpret results 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-loads purpose, then query guidance, then retrieval mechanics, then follow-up routing rules. Six sentences with no repetition of schema or annotation content, and each 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?

With no output schema, the description fills the gap by naming the salient result fields and the truncation signal, and it explains how to handle each follow-up case. Nothing material for a correct call or correct result interpretation 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 baseline is 3, but the description adds real meaning: it constrains the query parameter's shape (focused key terms, not the whole user message) and reinforces that brain must come from list_brains. It does not explain kind or entityType, which the schema already handles adequately.

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 saved Brain memories") and immediately clarifies what a memory is (singular fact or short Markdown mini-doc). This clearly separates it from siblings like get_memory (single fetch by id), list_brains (enumeration), and the mutation tools.

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 query-construction advice ("short, focused query with the key people, entities, preferences, or topics... not the full user message") and hard routing rules: call get_memory_versions when versionCount > 1, call get_memory when truncated: true, and always pass brain from list_brains. Both when-to-use and which-alternative conditions 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 disclose destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=false. The description adds important behavioral context beyond that: new content replaces the old content, and the previous version is kept. It does not cover permissions, failure modes, or response details, but the replacement and version-retention behavior is a meaningful addition.

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 tight sentences, front-loaded with the trigger and purpose. The content-format sentence and the replacement/version sentence each add distinct value with no wasted 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?

For a mutation tool with seven parameters, 29% schema coverage, and no output schema, the description covers the core operation well: when to use it, content format, and replacement/version behavior. However, it leaves several parameters unexplained, which matters given the low schema coverage. Annotations cover the safety profile, so the remaining gap is mainly parameter completeness.

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 only 29%, so the description must compensate for several undocumented parameters. It explains the content format and size, but says nothing about memoryId, kind, category, confidence, or entityType, and gives little beyond the schema for brain. Most parameter meaning is left to the schema despite low coverage.

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: update an existing Brain memory. It also scopes the action to correcting or changing existing content, which distinguishes it from adding a new memory. However, it does not explicitly name siblings such as add_memory or delete_memory, so sibling differentiation is implied 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?

It gives a clear usage trigger: when the user asks to correct or change an existing memory. It does not state when not to use it or explicitly point to alternatives like add_memory for new memories or get_memory_versions for history, so it falls short of full when/when-not guidance.

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