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

Even though annotations already mark this as destructive, the description adds valuable nuance: 'Only modifies the fields you specify; all other data is preserved.' It also discloses the write-tier approval behavior, including the from-now-on vs just-once approval distinction and the 'card is the yes' interaction. This goes well beyond the structured annotations.

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 dense but every sentence earns its place: purpose, use cases, routing prerequisite, and approval workflow. It is front-loaded with the core action and uses compact segments for routing and authorization guidance without fluff.

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 and a complex nested updates parameter, the description plus the rich schema is fully sufficient. It tells the agent when to call it, what to do first, how it mutates, what is preserved, and what approval expectations apply. Nothing essential 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?

The input schema already covers both parameters thoroughly, including the REPLACES semantics for dos/donts and the faith_substance invariant. The description adds no new parameter-level detail beyond restating the partial-update behavior, so the baseline 3 is appropriate.

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 opens with a clear verb+resource pairing: 'Update the company's voice profile.' It then lists concrete uses (add/refine DO/AVOID, style descriptor, reading level, subject), which makes it unambiguous what this tool is for and distinguishes it from getters like get_voice_profile and other update_* 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?

The description gives an explicit 'Use when the operator wants to tune their voice' condition and a concrete routing instruction: 'Call get_voice_profile first to see current values before calling update_voice_profile.' It does not explicitly name when-not-to-use cases or alternative tools, so it stops just short of a full 5.

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