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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description exposes a critical behavioral trap: for update, it states the endpoint SUBSTITUI both workflowJson and checklistJson and advises reading the piece first. It also explains that create returns the new piece id, that checklist toggles done/pending, and that bulk execution is supported via piece_ids. These are non-obvious side effects and execution details that an agent needs.

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 action-by-action structure is organized and the update replacement warning is front-loaded within the update bullet. But the description is longer than necessary for a checklist-flattened tool, and the extensive create/update details are likely extraneous given the tool name and '[Flattened action: checklist]' signal.

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?

For a checklist action, the core requirements are present: piece_id, data {itemId, done}, and bulk support. Yet the description doesn't explain how bulk piece_ids interact with data, what the response looks like (no output schema exists), or how to encode data as a string. The mixed create/update/checklist coverage further reduces confidence in whether this tool can be invoked safely without extra assumptions.

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?

With 0% schema description coverage, the description compensates substantially by detailing what goes inside data for each action, including required fields, the exact-one-of constraint between basedOnTemplateId and workflowJson, optional fields, and the {itemId, done} shape for checklist. However, it does not clarify that data is a string in the schema, nor what the account parameter means, and bulk semantics are only vaguely stated.

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 names a clear resource and multiple actions ('Cria ou atualiza uma peça no catálogo do iClips, ou marca um item do checklist'), but it is ambiguous which actions actually apply to this tool. The name 'write_checklist' and the line '[Flattened action: checklist]' suggest only the checklist action is available, yet the description documents create/update in full, blurring the distinction from sibling tools like iclips_pieces_write_create and iclips_pieces_write_update.

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?

There is useful prerequisite guidance ('Use iclips_workflow_templates para descobrir o basedOnTemplateId' and 'leia a peça antes com iclips_pieces action=get'), but the description never says when to choose this tool over the existing write_create/write_update siblings. It even documents create/update behavior as if those actions are available here, so an agent could be misled into using this tool for tasks that belong to other tools.

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