set_character_portrait

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

No annotations exist, so the description carries the full transparency burden. It discloses side effects: changing the portrait invalidates and rebuilds derived assets (three-view sheet, hairstyle/body reference), rebuilds the face lock, AI regeneration will not overwrite by default, and stale_frames in the response are contaminated. It even explains the failure mode of external images lacking identity/style anchors.

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 long but front-loaded with the core purpose, and the ★ markers and imperative warnings make the dense workflow guidance scannable. Minor redundancy exists: it repeats the schema's '二选一' rule and ends with '免费,' which does not add operational value.

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 annotations and no output schema, this is unusually complete. It covers input selection, side effects, response contents (stale_frames), exact remediation steps, and an explicit anti-pattern to avoid. An agent can invoke the tool and correctly handle its aftermath without additional research.

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 67%: file_path and image_url already have descriptions including the mutual-exclusion rule and COS auto-upload, and the description largely restates those. character_id has no schema description and the description does not explain its semantics beyond what the tool name implies. The description adds general context but does not meaningfully compensate for the missing parameter-level explanation.

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 defines a specific operation: using a customer-supplied image as the character's portrait, explicitly calling it the identity anchor with higher priority than AI-generated portraits. This clearly differentiates it from portrait-generation sibling tools like generate_character_portraits, even without naming them directly.

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?

It gives concrete when-to-use context (customer's own image as portrait) and provides an explicit workflow after a portrait change: regenerate each stale_frame using quote_shot_frame + generate_shot_frame. It also gives a direct when-not instruction: never hand-craft first/last frames and call upload_shot_frame, because it causes character/style drift.

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