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

Annotations already declare this is a non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds genuinely useful context beyond that: no credit cost and that omitted fields are left untouched. It does not explain merge vs replace behavior for nested objects/lists or what an update response looks like.

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, front-loaded with purpose and cost, with no filler. The enum listing at the end is redundant with the schema and takes space that could have gone to the undocumented 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?

A 19-parameter nested mutation with no output schema and near-zero schema descriptions needs far more: what the Brain represents, whether nested brand_voice and arrays merge or replace, and which fields are mutually relevant. The definition covers only the cheapest facts, leaving an agent to guess at the rest.

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 11% across 19 parameters, so the description should compensate and largely does not. The only parameter detail given (brand_voice 0-100, category and icp_gender enums) merely restates what the schema already encodes, while competitors, key_messaging, sitemap_url, shopping_feed_url, and the ICP fields are never explained.

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 ('Update this project's Brain'), and the read counterpart get_brain exists among siblings, so the agent can place it. 'Brain' is domain jargon that isn't defined, and no sibling is named explicitly, so differentiation is inferred 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?

'Send only the fields to change' is a concrete invocation guideline (partial-update semantics) and 'Does not spend credits' hints at cost considerations. However, it never says when to prefer this over get_brain, what prerequisites exist, or whether an empty call is valid.

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