set_shot_name_card

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

With no annotations, the description carries the full disclosure burden and handles it well: it states the operation is pure data, that the card is burned into the final composite, that preview and final cut will use consistent calligraphy fonts, and that an empty name clears the card. These are meaningful behavioral details beyond what the schema conveys; no contradictions.

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 compact and front-loaded: purpose, clearing semantics, cost/use case, then a high-value warning. Every sentence earns its place, and the warning about manual overlay prevents a costly workflow mistake. No filler or redundant restatement.

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 simple 5-parameter data-setting tool with no annotations and no output schema, the description provides enough context to call it correctly: what it does, how to clear, when it's suitable, and the main failure mode to avoid. Minor gaps like error handling or response format are not critical for this tool.

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 80%, so the schema already documents most parameters: name rendering/clearing, seal default, side enum, and duration default. The tool description adds rendering context and the empty-name clearing rule, but it doesn't materially expand on parameter meaning beyond the schema. 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 specific verb phrase 加/改/清 (add/modify/clear) and names the exact resource 「角色名卡」 for a shot, including what the card looks like (vertical character name + vermilion seal, calligraphy font, burned into the final cut). This makes the tool's purpose unmistakable and distinguishes it from other set_* sibling tools 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?

It gives an explicit use case (labeling characters in group scenes) and an explicit anti-pattern (don't manually overlay text in a downloaded video and re-upload, because it bypasses renderer font/seal assets and causes preview/final mismatch). It doesn't name a sibling tool as an alternative, but it clearly conditions when to use this tool and when not to.

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