rastermoves_refine

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

Beyond the annotations, the description discloses that this is an asynchronous operation returning a retained background job and that the agent must poll danceflow_job_status, which is not derivable from the hints. It also declares the effect profile (write, inference) and points to danceflow_component for conditional inference/download effects, adding real context on permissions. It does not explain the destructiveHint=true consequence (e.g., overwriting an existing output file), which is the remaining gap.

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 short, front-loaded sentences with no filler: purpose, then return/polling behavior, then permission flags. Dense terminology ('retained baselines', 'retained background job') is slightly opaque but each sentence carries distinct information.

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?

An output schema exists, so return-value explanation is unnecessary, and the async/polling model plus effect flags are covered. For a destructive, async tool with a large nested parameter surface, though, it omits overwrite semantics and prerequisites such as having the refiner weights cached or downloaded (rastermoves_download_refiner). Adequate but with clear gaps.

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 nested 'arguments' object contains roughly 28 properties with essentially no schema descriptions, and the description explains none of them — no meaning for strength, tile, overlap, refiner, resume, or max_output_mp. Terms like 'cached weights' and 'retained baselines' gesture at cache_dir/resume behavior but do not define them. With 50% schema coverage and a large undocumented parameter surface, the description fails to compensate.

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 ('Refine images') plus a scoping constraint ('at unchanged dimensions') that implicitly separates it from rastermoves_upscale in the sibling list. It also names the follow-up tool (danceflow_job_status) and the introspection tool (danceflow_component), so the agent can place the tool in a workflow. It stops short of naming rastermoves_upscale or rastermoves_plan_refinement explicitly as the alternatives.

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 'poll danceflow_job_status' sentence gives a concrete post-invocation step, and 'unchanged dimensions' hints at when this is preferred over upscaling. However, there is no explicit when-to-use/when-not guidance against the many sibling tools (rastermoves_upscale, rastermoves_plan_refinement, rastermoves_refiners), so selection still relies on inference.

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