workflowmoves_integrate_epk_media

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

Adds real behavior beyond the annotations: the output is a retained background job requiring polling, base effect is 'write', and inference/download effects are conditional and must be confirmed via danceflow_component. The permission-flag framing complements rather than repeats the readOnly/destructive hints. It still doesn't say what gets overwritten if output/record paths exist.

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?

Four short sentences, front-loaded with purpose before the async and effect details. Dense but every sentence carries operational information; no redundant restatement of the tool name.

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?

Output schema exists so return values are partly covered, and the async polling model plus permission flags are explained. Still missing is what the transformation actually produces (which media gets integrated), prerequisites for the profile, and behavior on conflicting output/record paths — significant gaps for a write-effect tool.

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 50% and the four required string arguments (source, profile, output, record) carry only pattern/length constraints, no descriptions. The description implies profile is an explicit media profile and record is an edit receipt, but source and output are left to inference.

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 and resource ('Transform local HTML') plus the operative mechanism ('using an explicit media profile') and a side artifact ('retain an edit receipt'). It is distinguishable from audit/compose siblings, though the 'epk media' jargon assumes domain familiarity.

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 useful post-call routing — poll danceflow_job_status for the retained job, inspect danceflow_component for conditional effects. However, it never says when to choose this over related siblings like workflowmoves_compose_epk_cover or the audit tools, so selection guidance is incomplete.

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