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

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes further by specifying that refs REPLACES the reference set (not appends) while traits MERGES, and that unlink removes links by id. These replace-vs-merge semantics are the highest-risk behaviors here and are disclosed precisely, plus the tool is stated to be free.

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?

Front-loaded with purpose, then parameter semantics in a tight telegraphic sequence with no filler sentences. The dense clause-stacking ('pictures you own as [{kind: generation|asset, id, role}]') is efficient but costs some readability, keeping it below 5.

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 9-parameter, nested-object, create-or-edit tool with no output schema, it covers the dual mode, all mutation semantics, the enum-constrained fields, and closes the loop by explaining where the returned id is consumed (storyboard cast/places, entity_ids, or @slug in a prompt). Nothing an agent needs to call it correctly is missing.

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?

With only 67% schema coverage, the description compensates heavily: it explains that description maps to bio.description, that traits merges any other trait, that links' to_type is the target's kind or product, and it enumerates valid refs roles per kind (character face/front/three_quarter/side/back/detail; place wide/angle/detail; prop front/side/back/detail) that the schema leaves as a bare string.

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+resource pair ('Creates or edits a character, prop, place, skin or look') and immediately scopes the tool with 'and links it to others.' It is clearly distinguishable from siblings like list_entities or delete_asset, and it names the entity kinds matching the schema enum.

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 branch rule: 'Without entity_id it finds or creates by kind and name; with entity_id it edits that one,' which is exactly the decision an agent needs. It also routes to list_entities for link ids. It lacks an explicit when-not-to-use clause (e.g. vs. generate_sheet or storyboard), so 4 rather than 5.

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