compose_variations

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

Without any annotations, the description carries the burden of disclosing side effects. It transparently mentions that it saves outputs to numbered files and returns the list of paths, but it does not disclose whether it modifies the current project state, whether it overwrites existing files, or whether it has any destructive or non-destructive side effects. Partial transparency only.

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 two sentences, concise, and information-dense. It states the core action, the output behavior, and the intended use case without any fluff or redundancy.

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?

The description is incomplete given the complexity of the tool. It has four parameters including a nested object (extra_args), but no explanation of how extra_args modifies the composition, what format it expects, or how it interacts with count. It also leaves unclear whether the returned paths are absolute or relative, whether the operation is synchronous, and what happens if the composer fails. These gaps prevent an agent from using the tool confidently in nuanced contexts.

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 schema has zero descriptions for the four parameters, so the description must compensate. However, it does not explain any parameter: it never mentions composer_name, out_path_prefix, count, or extra_args, nor how they map to the described behavior. The phrase 'N times' vaguely references count, but no direct parameter explanation is given. Since schema coverage is 0%, a score of 1 is warranted.

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 a specific verb (run a composer) and resource (composer with multiple seeds), and it distinguishes itself from siblings by emphasizing variation generation and selection, which no other sibling tool does. The phrase 'so you can render all and pick the best' further clarifies its unique purpose.

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 for when to use the tool: when the user wants multiple compositional variations to compare and choose the best. However, it does not explicitly mention when not to use it or name alternative tools (e.g., compose_lofi_track or compose_and_reload), so it lacks explicit exclusions.

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