likenessforge_faces

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

Goes well beyond the annotations: it discloses that the operation returns a retained background job, enumerates base effect flags (write, inference, download, network), and flags that inference/download effects are conditional and should be verified via danceflow_component. This meaningfully informs the agent about statefulness and side effects that readOnlyHint=false and openWorldHint=true alone do not convey.

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?

Three compact sentences, front-loaded with the action, then follow-up routing, then effect flags. Little wasted wording, though the effect-flag sentence is terse and could be clearer about which flags are always versus conditionally active.

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 that an output schema exists (so return values needn't be explained), the description covers the essential background-job/polling model and effect disclosure. It is complete enough to invoke correctly, with only minor gaps around detector selection and input parameter meaning.

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?

At 50% schema coverage, the description adds some meaning by naming the 'selected canonical detector' concept, but it does not explain image vs. preview inputs or the detector selection logic that the schema leaves undocumented. It partially compensates but leaves gaps for the image/preview parameters.

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?

States a specific verb+resource ('Detect and index faces') plus the mechanism ('selected canonical detector'), which is enough to distinguish it from training-oriented siblings like likenessforge_train_lora. It does not explicitly contrast with sibling tools, keeping it short of a 5.

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?

Gives follow-up routing ('poll danceflow_job_status') and points to danceflow_component for conditional effects, which is useful context. However it never states when to choose this tool over alternative face/LoRA workflows or what preconditions (e.g. model availability) apply.

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