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

With no annotations, the description carries the full behavioral burden, and it does so thoroughly. It discloses that this is an async job, that it costs 50 credits, that the immediate response contains id and credits_charged, and that the eventual project can reach complete/error/canceled states with downloads. It also warns that hotlinked URLs can fail, adding important reliability context.

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 and cost statement up front, followed by two focused guidance bullets. Every sentence carries operational value, and the async workflow and file upload constraints are presented in a scannable format without rhetorical filler.

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 async nature, cost implications, required asset, and nested schema, the description covers all critical contexts: how to obtain the final result, how to handle file paths reliably, and what to expect in the immediate response. The output schema exists, so there is no missing return-value burden. An agent can invoke and successfully complete the workflow using this description alone.

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 schema already covers 67% of parameters, including name and style.prompt descriptions. The description adds substantial semantics for assets.image_file_path by explaining preferred file_path sources, the upload-URL flow, and risks of direct URLs. This goes beyond the schema's basic 'image used to generate the headshot' explanation, though it does not elaborate on name or style.

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 'Create an AI headshot,' a specific verb plus a clear resource, and immediately distinguishes it from the many sibling create_image tools by centering the headshot use case. The tool name reinforces this, so an agent can select it without ambiguity.

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 explicitly tells the agent what to do after invocation: call wait_for_image_project with the returned id or poll the endpoint until completion, with concrete statuses. It also gives file_path selection guidance with a clear 'when in doubt, use the presigned upload flow first' directive, including when direct URLs may be acceptable.

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