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

Annotations indicate a non-read-only, non-destructive write, and the description adds useful constraints: update requires a document 'em andamento', delete is a soft-delete, and create requires exactly one file source among five types. However, it does not explain side effects such as default signer emails, return format, or permission requirements; it also includes behaviors that are not this tool's actual flattened action. There is no direct contradiction with annotations.

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 a large multi-action reference with seven bullets, most of which are irrelevant to the flattened create tool and duplicate sibling tool names. While the bullet structure is readable, it includes substantial extraneous content and buries the disambiguating '[Flattened action: create]' at the end.

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 complex create operation with nested objects and no output schema, the description gives a fairly complete field specification for `data` and notes conditions like soft-delete and update state. It is incomplete regarding `account`, the return value, and the fact that the other listed actions are not available through this 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 description coverage is 0%, so the description compensates strongly for the main `data` parameter by naming required fields (name, signers[]), nested signer attributes, the mutually exclusive one-file-source set, and optional fields. However, `account` is not described, and `doc_token` is only explained implicitly for non-create actions, leaving some schema parameters without semantic grounding.

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 opens with 'Criar/alterar documentos de assinatura' and enumerates seven write actions (create, create_from_template, update, delete, refuse, place_signatures, add_extra_doc), making the tool's actual scope ambiguous. The final '[Flattened action: create]' hint disambiguates to create, and the create action is described with required fields, but the broad action list undermines separation from sibling tools such as zapsign_documents_write_create_from_template and zapsign_documents_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?

No explicit when-to-use or alternative guidance is provided. The description lists create_from_template, update, delete, and other operations as if they might be available here, but it never clarifies that this flattened tool only executes create and that sibling tools should be used for the other actions. The only conditional note is for update ('só com doc em andamento'), which does not help tool selection.

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