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

Annotations already declare the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=false). The description adds two facts the annotations cannot convey: omitted fields are left untouched, and existing videos retain the old look, so the change is not retroactive. That non-retroactivity is exactly the kind of side-effect disclosure that matters for a mutation 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?

Two short sentences, the mutation scope is front-loaded, and the caveat about existing videos follows immediately. No filler or repeated title text.

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, it covers partial-update semantics and one downstream consequence, which is more than most. Still missing: what happens if character_id is invalid, whether changing a look affects videos already scheduled or in progress, and whether name collisions are rejected.

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?

Top-level schema coverage is effectively 0% for character_id, name, and look, so the description has to compensate. It clarifies that both name and look are optional and partially applied, which is helpful for a nested object, but it says nothing about character_id (must reference an existing character) or the name length bounds. The nested enum descriptions in the schema carry the bulk of the field-level meaning.

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 (changes) and resource (a character) and names the two mutable field groups, name and look. It is reasonably distinguishable from create_character or delete_character, though it never explicitly contrasts with a sibling.

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 parenthetical 'only the fields you send' establishes partial-update semantics, which is real usage guidance and tells the agent not to resend the whole look object. However, there is no explicit when-to-use, no pointer to list_characters for obtaining character_id, and no stated alternative for identity changes.

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