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

Annotations already declare this is a write (readOnlyHint=false) that is idempotent and non-destructive, so the safety profile is covered. The description adds a genuine content constraint not present in structured data: rules are style-only and may not permit invented facts, stories, quotes, or numbers. It does not discuss auth/workspace permissions beyond the schema.

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 action and scope, then trigger and id source, then the content constraint. No filler or repetition of schema/annotation data.

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 an output schema covering returns and annotations covering the safety profile, the description supplies purpose, trigger, id source, and a content constraint. It omits whether the edit is reversible (undo_voice_change exists), a minor gap rather than a blocking one.

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 baseline is 3. The description goes beyond it by telling the agent where ruleId originates (get_voice_profile) and by constraining the text parameter to style-only wording, adding meaning the schema's maxLength/description does not convey.

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 (Reword) and resource (one rule in the writer's voice profile), and the singular scope distinguishes it from siblings like add_voice_material and remove_voice_rule. An agent can tell what it does without opening the 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?

"when the writer asks you to change it" gives a clear trigger condition, and it points to get_voice_profile as the source of the rule id. It stops short of naming explicit exclusions (e.g. use remove_voice_rule to delete, add_voice_material to append), so it is clear context without full alternative routing.

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