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

Annotations provide readOnlyHint=false (mutation) and destructiveHint=false. The description adds the single-face limitation and also includes quality claims ('remarkably realistic results'), but does not mention important behavioral aspects such as async/polling behavior (though polling is in schema), side effects on source files, authentication needs, or rate limits. It partially compensates for minimal 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 begins with a clear purpose but then includes promotional language ('remarkably realistic results', 'facial expressions, lighting, and skin tones are finely tuned') that adds little operational value. The 'Sample usage cases:' line is incomplete, making the structure feel unfinished. Overall, it is not concise, with unnecessary 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?

Given the complex request schema with multiple variants (URL vs file ID), the description should explain at a high level that the tool requires a source video, a reference face, and a duration. It only mentions face swapping generically. The output schema exists and reduces the need to explain return values, but the description still omits important selection context such as polling behavior and input requirements, making it incomplete for a tool of this complexity.

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 description contains no information about parameters. Schema description coverage is 50% at the top level (polling has a description, request does not), and while the nested request properties have descriptions, the description text does not summarize what inputs are needed (e.g., source video URL, reference image URL/ID, duration). The trailing 'Sample usage cases:' is empty and adds no value.

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 clearly states the tool's function: 'replace one person's face with another in a video' using AI. The phrase 'Video face swapping' and the specific API reference distinguish it from image-based face swap (AI-Face-Swap). The note about 'single face only' further clarifies scope.

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 implies usage for video face swapping and includes a key constraint: 'supports video with single face only.' However, it does not explicitly state when to prefer this over sibling tools like AI-Face-Swap, nor does it provide exclusions or alternatives beyond a generic 'contact us' for customization.

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