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

Annotations already signal readOnlyHint=false and destructiveHint=false, and the description adds useful field-level behavior such as required name/email and optional auth_mode/send_automatic_email. It does not disclose side effects like whether adding a signer triggers an invitation or whether duplicate adds are possible, but it does not contradict the 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 overlong for a single flattened add tool because it documents update, remove, and sign operations that belong to sibling tools. Only the add bullet is relevant, and the clarifying '[Flattened action: add]' note appears at the end rather than front-loaded.

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?

There is no output schema and the description does not explain return values, errors, or prerequisites for adding a signer. It also fails to clarify why signer_token is present in the input schema for an add-only action, making the tool incomplete for reliable invocation.

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%, but the description compensates by enumerating the data fields: name*, email*, and optional phone_country, phone_number, auth_mode, lock_name/email/phone, qualification, and send_automatic_* flags, including auth_mode enum values. However, account and signer_token remain unexplained in the add-only context.

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 the vague phrase 'Gerenciar signatários no ZapSign' and lists add, update, remove, and sign actions, so it does not crisply isolate this tool's add-only purpose. However, the line 'add (doc_token, data): adiciona signatário' and the trailing '[Flattened action: add]' do make the core operation identifiable.

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 action list implies when each operation is appropriate, e.g., 'atualiza (só antes de assinar)' and 'remove (não pode remover quem já assinou)', but it never explicitly says this tool is only for adding signers or points to sibling tools as the alternatives for update/remove/sign. Guidance is present but implied rather than explicit.

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