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

The description adds meaningful behavioral detail beyond the readOnlyHint and idempotentHint annotations: list returns only id, name, and description without workflowJson, while get returns full workflowJson in batch with per-id error reporting. This is valuable operational context for an agent.

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 well-structured with a short lead sentence, bulleted actions, and a cross-reference to iclips_pieces_write. The trailing '[Flattened action: list]' marker is somewhat confusing and not clearly useful to the agent, but the overall size is appropriate.

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?

With no output schema and no parameter descriptions, the description does a good job of explaining list vs get return contents and how to use the resulting id. It is still missing an explanation of the account parameter and how the get action is triggered explicitly, but the core invocation paths are understandable.

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 description explains that template_ids triggers the get action and returns the full workflowJson, which compensates for the 0% schema coverage on that parameter. However, the account parameter is not explained at all, so parameter semantics are only partially covered.

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 the tool reads iClips workflow templates and distinguishes list vs get behavior. However, it does not explicitly differentiate itself from the sibling iclips_workflow_templates_get, and the inclusion of a get action inside a list-named tool adds mild ambiguity.

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 clear context for when to use the list action vs the get action via template_ids, and it tells the agent to use the returned id as basedOnTemplateId when creating a piece. It does not mention the sibling get tool or state when not to use this tool, so it falls short of explicit alternative routing.

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