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

With no annotations present, the description carries the full disclosure burden and largely succeeds. It reveals the async job nature (returns id and credits_charged immediately, requires polling or a wait helper), the credit cost, terminal statuses (complete/error/canceled), that completed projects include downloads with direct URLs, and the failure modes of hotlinked URLs. This goes well beyond what a bare 'create' description would provide, though it stops short of detailing error/edge behaviors or idempotency.

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 well-structured: a one-sentence purpose lead, a pricing note, then organized MCP guidance split into async workflow and file-path handling. Every section earns its place and the most decision-critical facts (async behavior, cost, wait helper) are front-loaded. It is moderately long but the density of actionable information justifies the length; no filler or tautology.

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 tool's real complexity — async execution, two face-swap modes with conditional parameters, nested assets object, credit billing, and output retrieval — the combination of description and 100%-covered schema is nearly complete. The description covers the async lifecycle and file acquisition; the schema covers mode semantics and conditional requirements; an output schema exists so return values need not be restated. The only notable gap is that the prerequisite step of calling face_detection_detect_faces for individual-faces mode appears only in schema text, not in the operational guidance.

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% with rich per-field descriptions covering conditional requirements (source_file_path for all-faces, face_mappings for individual-faces), maxItems, examples, and the face-detection provenance of original_face. The description adds genuine value by explaining how *_file_path values should be sourced — prefer Magic Hour file paths or upload-URL file_paths over unstable hotlinks — which directly informs correct parameter construction. This exceeds the baseline-3 expectation for high schema coverage.

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 states a specific verb+resource ('Create a face swap photo') and adds distinguishing context: the 10-credit cost and subscription-dependent output dimensions. It is clearly the photo variant of face swap versus the sibling face_swap_create_video, though it never explicitly names that sibling or differentiates from overlapping tools like head_swap_create_image or body_swap_create_image, leaving some differentiation to inference.

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 MCP guidance is strong on operational workflow: it explicitly tells the agent this is async, to call wait_for_image_project with the returned id, or poll until complete/error/canceled, and how to source *_file_path values. However, it provides no when-to-use vs. alternatives guidance — nothing explains when to choose this over face_swap_create_video, head_swap_create_image, or ai_face_editor_edit_image. Selection among overlapping siblings is implied only by the word 'photo'.

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