Save a creator

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

Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It discloses key non-obvious behaviors: saving is FREE and renders nothing, and it explains the nuanced consent and source requirements for real people. This adds meaningful context beyond the annotation fields and helps the agent avoid misuse. It does not mention overwrite or duplicate behavior, but for a save action this is not a critical omission given the explicit 'Add a portrait' framing.

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 detailed but not bloated. It front-loads the core purpose and then adds necessary usage and constraint context. The use of all-caps 'LIKENESS' and 'REAL' draws attention to critical distinctions. Each sentence contributes information without redundancy. It could be slightly tighter, but it remains well-structured and readable.

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 tool with 7 parameters, 2 required, and no output schema, the description covers all essential aspects: main purpose, usage flow, prerequisites (public URL, consent), parameter semantics reinforcement, and behavioral notes (free, renders nothing). It even implies interactions with sibling tools (list_creators, generate_avatar). Nothing critical is missing for an agent to call it correctly and safely.

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 100%, so the baseline is 3. The description largely reiterates what the schema already states (e.g., image is a public URL, name is what to call the creator, look is canonical appearance). It adds emphasis on the source and consented constraints, but these are already in the schema. It does not introduce new parameter-level meaning beyond clarifying the relationship to other tools (e.g., URL reused in generate_avatar/video), which is more usage guidance than parameter semantics. Thus, 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 clearly states the tool's purpose: add a portrait to the workspace's reusable CAST so the same person can star in future ads. It explicitly identifies the API as the headless twin of the app's '＋ ▸ Pick a creator ▸ save' flow, which distinguishes it from sibling tools like list_creators, delete_creator, and generate_avatar. The verb 'Add' plus the resource (portrait to CAST) is specific and unambiguous.

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 provides clear context on when to use the tool: anytime you need to save a person to the reusable CAST for future ads. It explains the flow (pass a portrait URL and name, then list_creators returns them and the URL can be reused in other tools). It gives a critical usage rule about source and consented parameters, and indicates that saving is free and renders nothing. It does not explicitly name alternatives or state when NOT to use it, but it implies that once saved, you should use list_creators to retrieve existing creators, which is adequate guidance.

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