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

With no annotations present, the description carries the full burden of behavioral disclosure. It adds one useful behavior, 'Auto-reindexes,' but does not explain whether the file must already exist, whether the operation is irreversible, or what side effects occur beyond reindexing. This is a meaningful gap for a mutating 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?

The description is extremely concise, with only two short sentences. The core operation is front-loaded first, and the second sentence adds a relevant behavioral detail. There is no wasted wording.

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 2-parameter tool this is simple, but without annotations and with no sibling differentiation or parameter guidance, the description is incomplete. An agent can guess how to call it, but not confidently understand edge cases like missing files, reindex behavior, or when to prefer brain_write.

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?

Input schema description coverage is 0%, so the description must compensate. It does not explain the expected format of 'path' or 'content,' nor does it clarify relative versus absolute vault paths. The parameter names are somewhat self-explanatory, but the description adds little semantic value beyond what the schema already exposes.

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 the exact operation: 'Append to a vault file.' The verb and resource are specific, and 'append' inherently distinguishes it from sibling tools like brain_write. It gives an agent enough clarity to understand what this tool does.

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 does not explain when to choose this tool over related alternatives such as brain_write. 'Append' implies a use case, but there is no explicit guidance about when appending is appropriate versus overwriting, creating, or logging.

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 burden of behavioral disclosure. It reveals the batch limit of 5 and the read-only nature, but says nothing about error handling, partial failures, truncation behavior, or path interpretation. This is adequate but leaves room for richer disclosure.

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 a single, front-loaded sentence with no filler. Every word contributes meaning: 'up to 5' sets the limit and 'in one call' signals batching.

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 tool with no annotations and incomplete schema descriptions, the one-line description is too thin. It omits key operational details like max_chars semantics, what happens if more than 5 paths are provided, and path format expectations. The output schema may cover return shape, but it cannot compensate for missing parameter and edge-case 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 0%, so the description must compensate. It vaguely implies paths refer to vault files, but does not explain what 'paths' means (e.g., relative vs absolute) or what 'max_chars' controls (per file vs total, truncation behavior). The parameter titles alone are insufficient.

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 ('Read'), a clear resource ('vault files'), and a distinguishing constraint ('up to 5... in one call'). This clearly separates it from the sibling brain_read (single-file read) without needing to inspect 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?

The phrase 'in one call' conveys that this tool is for batching multiple file reads, which implies use when you need several files at once. It does not explicitly name alternatives or state when not to use it, but the context is reasonably clear given sibling names.

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 behavioral burden. It discloses the ripgrep backend and the output shape, but does not mention read-only behavior, limit truncation, no-match behavior, hidden-file handling, or regex flavor. It provides some useful context but not a fully transparent behavioral profile.

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 zero filler. It front-loads the core function and then gives the output format, so every word earns its place.

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 tool is simple and has an output schema, so the description does not need to explain return values. However, it omits the search scope (what is being searched), how the limit applies, and any guidance about alternatives, leaving an agent to infer several operational 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 compensate. It clarifies that 'pattern' is an exact or regex pattern, but it says nothing about the 'limit' parameter, leaving its meaning and effect to inference from the name and default value.

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 that the tool performs exact or regex search and that it returns file:line:match output. It distinguishes itself from the likely semantic sibling brain_search by emphasizing exact/regex search, though it never explicitly names the resource being searched (the 'brain').

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 'exact/regex' phrasing implies when this tool should be used, and the sibling brain_search likely covers semantic search, but the description gives no explicit when-to-use or alternatives guidance. Usage context is implied rather than 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?

With no annotations, the description carries the behavioral burden. It discloses the write/persist effect and adds the useful auto-reindexing side effect, but it does not mention whether duplicate lessons overwrite or append, whether authorization is needed, or what happens to existing index entries. This is adequate but incomplete.

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 with the primary action front-loaded and no filler. Slightly more structure could pack parameter guidance into the second sentence, but as written it is a model of brevity.

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 description is too sparse for a tool with four undocumented parameters, no annotations, and an output schema. It fails to explain parameter roles, overwrite/idempotency behavior, indexing side effects, or when this tool is preferable to the write/append/log siblings. Even with an output schema, the missing context leaves an agent uncertain about 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%, so the description must compensate, but it does not explain any of the four parameters. The path hint ('knowledge/agent-lessons/') vaguely suggests agent/category may organize storage, and parameter names are somewhat self-explanatory, yet the description adds no explicit semantics for body, agent, category, or context.

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 ('Persist'), a specific resource type ('reusable lesson'), and an explicit target path ('knowledge/agent-lessons/'). This clearly distinguishes it from generic persistence siblings like brain_write and brain_append by focusing on the lesson-specific purpose and auto-reindexing.

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 'reusable lesson' implies this tool is for storing knowledge worth retaining, but the description does not explicitly state when to prefer it over brain_write or brain_log, nor does it mention when not to use it. Usage context is only implied, not specified.

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 must carry behavioral disclosure. It does communicate that the tool lists files, scoped to the vault, and respects depth and pattern limits. However, it does not disclose details like whether path is required, how hidden files are handled, or whether the listing is recursive by default.

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 a single, front-loaded sentence that says exactly what the tool does with no filler. Every word earns its place, and the key constraints are included compactly.

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 tool is relatively simple, and the presence of an output schema reduces the need to describe return values. However, the description leaves gaps around the path parameter and usage guidance relative to siblings, so it is minimally adequate but not fully complete.

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 partially explains depth and pattern as 'limits', but it does not clarify the semantics of 'path', the meaning of depth values, or how patterns match file names. The path parameter, which defaults to empty, is left undocumented in both schema and description.

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 clear verb ('List') and resource ('files in the vault'), making the core purpose immediately obvious. It distinguishes itself from siblings like brain_read or brain_grep, but it does not explicitly name or differentiate from alternatives, so it stops 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?

There is no guidance on when to use brain_list versus brain_search, brain_grep, brain_stats, or brain_read. The description does not mention exclusions, preferred scenarios, or alternative tools, leaving the agent to infer usage from the tool name.

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 must disclose behavior on its own. It does reveal that entries are timestamped, stored in a dated markdown file, and that auto-reindexing occurs. However, it does not state whether the entry is appended or overwrites existing content, what side effects reindexing has, or what permissions or safeguards apply.

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 a single front-loaded sentence with no filler; the file-format detail and auto-reindex side effect are economically included. It loses a point because the extreme brevity omits parameter and usage context that the tool clearly 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?

Although an output schema exists so the return value need not be described, the overall definition is incomplete for a three-parameter tool with no annotations and 0% schema description coverage. It does not explain what type means, how agent and message are used, whether the file is appended, or why auto-reindexing matters, leaving an agent under-equipped to call it confidently.

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 the three parameters, but it does not mention agent, message, or type at all. The parameter meanings are left entirely to inference from their names, which is inadequate for an agent to know how to fill them correctly.

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 identifies a concrete resource (daily YYYY-MM-DD.md log) and the action of recording a timestamped entry, which clearly distinguishes it from generic brain_write or brain_append. However, it lacks an explicit verb like 'create' or 'append', and the purpose is more inferred from the name than fully 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 description implies a daily-logging use case but provides no guidance on when to use brain_log versus brain_write, brain_append, or brain_lesson. There are no stated conditions, exclusions, or references to alternatives, so an agent receives no routing help.

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 burden. The verb 'Read' effectively signals that this is a non-mutating, read-only operation, which is useful. However, the description does not disclose behavioral details like max_chars truncation, error handling, or any constraints beyond the basic read action.

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 a single, front-loaded sentence with no filler. Every word contributes meaningful information, making it highly concise and well-structured for a simple read operation.

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 input schema and output schema provide structured context, and the read action is simple enough that the description is mostly usable. Still, missing usage guidance and unexplained max_chars behavior leave small but real gaps. This is an adequate but not fully complete definition.

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 adds meaning to 'path' by specifying 'relative path', but 'max_chars' is left entirely to its title and default value, with no explanation of how it limits the read or what the effective behavior is. The description only partially clarifies the parameter surface.

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 and resource: 'Read a vault file by relative path.' It clearly communicates the tool's function and distinguishes it from sibling tools like brain_batch_read (multiple files) and brain_grep/brain_search (search-based access).

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 'by relative path' implies this tool should be used when the file path is already known, but the description does not explicitly state when to use it versus alternatives such as brain_batch_read, brain_grep, or brain_search. Usage context is present but mostly 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?

The description discloses core behavioral traits: it performs a hybrid dense/BM25 search with RRF fusion and can be narrowed by path_prefix. However, with no annotations provided, it does not explicitly confirm read-only behavior, return ordering, or any potential side effects, leaving some burden unmet.

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 extremely concise and front-loaded: the first sentence captures the core retrieval behavior, and the second adds the only notable parameter nuance. No filler or redundant information is present.

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 relatively simple three-parameter search tool with an output schema, the description provides the essential algorithm and scope control. It remains incomplete because it does not clarify how results are ranked, when to choose this over grep, or any implicit defaults, making it adequate but not fully self-sufficient.

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 adds meaning for path_prefix ('narrows scope') and says nothing about query semantics or how limit behaves, leaving the agent to infer those from parameter names alone.

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 indicates a technical search mechanism ('Dense + BM25 prefetch, RRF fusion') and an optional scope narrowing via path_prefix, which conveys that this is a hybrid retrieval tool over the 'brain' corpus. It does not use an explicit verb like 'searches' but the meaning is clear enough and distinguishes it from simpler grep/list operations.

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?

There is no explicit guidance on when to use brain_search versus sibling tools such as brain_grep or brain_list. 'Optional path_prefix narrows scope' offers parameter-level context but does not explain when hybrid search is preferred over alternative tools.

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 present, so the description must carry behavior disclosure. The listed metrics imply a read-only stats/diagnostic tool, but it never explicitly states that it makes no modifications or whether the embed service health check has side effects/dependencies. This is adequate but leaves the safety profile implicit.

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?

At eight words, the description is highly concise and every listed item adds information about the returned statistics. Its telegraphic noun-phrase style is mildly unpolished but not 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?

For a zero-parameter diagnostic tool with an output schema, the description is largely complete: it enumerates the available statistics and implies the read-only nature. It could add an explicit 'use for health/usage checks' clause, but an agent can safely invoke and interpret this tool from the current definition.

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 no parameter semantics burden. Per the 0-params baseline, the description does not need to compensate for any schema gaps.

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 (brain collection stats) and the concrete metrics included: size, disk usage, embed service health, and .md count. It lacks an explicit verb like 'returns' or 'reports', but the noun-phrase list is specific enough to distinguish this from sibling read/search/list 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?

Usage is implied: an agent needing aggregate collection statistics or service health would know to call this tool. However, there is no explicit when-to-use or when-not-to-use guidance, and no differentiation from brain_list or brain_search, which could also be considered for data collection questions.

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 burden of behavioral disclosure. It discloses atomicity but omits critical behaviors: what happens if the task is already claimed, TTL semantics, whether the claim is idempotent, and what state changes occur. For a coordination tool, these details are essential.

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 filler. It communicates the core action and purpose efficiently. However, the extreme brevity omits parameter and usage details, so while it is concise, it is not fully appropriate for the tool's complexity.

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 tool with three parameters, no annotations, and an output schema, the description is far too thin. It leaves the agent guessing about return values, failure modes, and interaction with sibling tools like brain_task_release. Only the atomic coordination context is provided.

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%, and the description names none of the three parameters. It does not explain the role of 'agent', the meaning of 'ttl_hours', or how 'task_id' is used. With zero compensation from the description, this is a fundamental gap.

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 verb ('claim') and resource ('task'), and enhances it with 'atomically' and the purpose 'for parallel agent coordination.' It conveys the tool's function and is implicitly distinguishable from sibling brain_task_release, though it does not explicitly compare them.

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?

There is no guidance on when to use this tool versus alternatives. The phrase 'for parallel agent coordination' implies a scenario, but it does not state when not to use it, prerequisites, or mention brain_task_release as the counterpart. An agent must infer the appropriate context on its own.

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 burden of behavioral disclosure. It does not explain what releasing actually does to the claim, whether it cannot be undone, what errors occur if the agent does not own the claim, or any side effects. This is a meaningful transparency gap for a mutating operation.

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 one short sentence with no filler. The core action is front-loaded, and every word contributes essential meaning.

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?

Despite being a simple tool with an output schema, the description lacks critical context: it does not specify what happens after release, how ownership is verified, or when this tool should be avoided. With no annotations to fall back on, the description leaves too much for the agent to infer.

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%, and the description does not explain the parameters beyond their names. 'task_id' and 'agent' are fairly self-explanatory, but the description adds no detail about formats, ownership semantics, or which agent identifier is expected. It fails to compensate for the complete lack of schema descriptions.

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 ('Release'), a specific resource ('a task claim'), and a clear condition ('if you own it'). It contrasts with the sibling brain_task_claim, making the tool's distinct function obvious without needing to inspect 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?

The phrase 'if you own it' provides a clear usage context: this tool applies only when the calling agent owns the claim. It does not explicitly name alternatives or exclusions, but the ownership condition is a strong practical guide and distinguishes intent from the sibling claim tool.

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 behavioral disclosure burden. It explicitly mentions the overwrite behavior and the auto-reindex side effect, which is useful. However, it does not disclose permissions, irreversibility consequences, or failure modes.

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 extremely concise: two short sentences with no filler. 'Create or overwrite a vault file' front-loads the core purpose, and 'Auto-reindexes' adds a valuable behavioral note without extra words.

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 tool is simple with only two parameters, and an output schema is present, so return-value explanation is unnecessary. Still, the description lacks parameter-level detail and sibling differentiation, leaving the agent to infer important invocation 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%, and the description does not explain the path or content parameters beyond the generic 'vault file' context. The agent can infer that path likely identifies a file and content is the file body, but the description adds little meaningful parameter semantics.

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 action and resource: 'Create or overwrite a vault file.' This clearly distinguishes it from sibling read, search, list, and append tools, and the name brain_write reinforces the purpose.

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 when to use the tool: when creating or overwriting a file. However, it gives no explicit guidance about when not to use it or which sibling tool should be preferred for alternative operations, such as brain_append for appending content.

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