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

The description adds valuable behavioral detail beyond annotations: partial updates preserve untouched fields, `outros_contatos` forces a full replacement, required fields for that replacement are listed, error messages identify missing fields, and enum casing/accent variations are normalized. The create/update contradiction lowers the score, but for the update path the behavior is disclosed thoroughly.

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 dense and generally organized, but it is quite long and includes a create branch that appears irrelevant to this update-only tool. The '[Flattened action: update]' note adds redundancy/confusion rather than clarity. Several sentences earn their place for the update semantics, but the overall structure could be tighter.

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 an update operation it covers partial-update behavior, enum values, the `outros_contatos` special case, required replacement fields, error hints, and bulk execution. Missing pieces include the `account` parameter, any return value/output description (no output schema exists), and a clear statement that this tool is update-only despite the create instructions.

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 by explaining `id` as the update key, `ids` as bulk support, and `data` as a JSON object with specific required contents. However, `account` is never explained, the actual JSON structure of `data` is incomplete, and the `action=create|update` parameter doesn't exist in the schema.

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 'Cria ou atualiza uma pessoa', which is a clear verb+resource, but the tool name `contaazul_person_write_update` and the embedded '[Flattened action: update]' note indicate this is update-only. Including a full `action=create` branch muddles the scope and overlaps with the sibling `contaazul_person_write_create`.

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 update path is well explained: `id` plus only changed fields in `data`, with partial-update semantics and the `outros_contatos` exception. However, the description instructs callers to use `action=create` on what appears to be the update-flattened tool, and it never routes agents to `contaazul_person_write_create` for creation. This makes the when-to-use guidance misleading.

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