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

With no annotations, the description carries the full burden and does it well: it discloses that the whole body is replaced, that the prior body is retained as a version (reversibility), that credentials are refused for content-policy reasons, and that an agent bearer token plus editor access are required for auth.

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 sentences, each earning its place: the replace-vs-append override is front-loaded, then permissions, then content and auth constraints. No filler or repetition of structured fields.

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 5-param mutation tool with no annotations and no output schema, the description covers the critical unknowns: overwrite semantics, version retention, auth, and content restrictions. It omits what the call returns and any size limits on body, which are minor gaps here.

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

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

Schema coverage is 100%, so the schema already documents name format, folder levels and defaults, and brain path syntax. The description only adds the meaning of mode ('append' to add to the end) and the default-brain behavior, which is marginal beyond the schema.

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

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

Opens with a specific verb+resource: 'Create or update a Brain file.' The word 'file' distinguishes it from the brain_create/brain_get siblings, though it never names brain_create explicitly, so an agent must infer the boundary between creating a file and creating a 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?

Gives clear situational guidance: omits the brain param to hit the default brain, requires editor access for shared brains, and recommends mode 'append' when adding to the end. It also points at brain_list for folder structure. No explicit 'don't use this for X' exclusion versus brain_create, so it stops 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.