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

Goes well beyond the annotations: discloses the key side effect that open tasks shift by the same number of days when the death line changes, that completed or undated tasks are untouched, that the server alone would not move them ('O Astrea sozinho não move as tarefas; esta tool move'), and that tag_ids replaces the whole list rather than appending. It also states what the response contains (each task with old and new date), which compensates for the missing output schema.

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?

Front-loaded with the critical id-preservation rule, then organized as tight bullets that each map to a parameter group. Slightly long and mildly repetitive around task movement ('...andam junto' followed by 'O Astrea sozinho não move as tarefas; esta tool move'), but no bullet is filler.

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 11-parameter mutation tool with no output schema and zero schema descriptions, the description covers inputs, side effects, opt-out flags, and even the shape of the response. Nothing an agent needs in order to call it correctly is missing.

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 must carry all 11 parameters — and it does: prazo_id, title, comments, responsible_id, tag_ids (with replace semantics), due_date (with the AAAA-MM-DD format), and the dias + data_inicial + contagem + considerar_recesso computation path, plus mover_tarefas with its false behavior. This is meaning an agent cannot derive from the bare 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?

States a specific verb and resource ('Edita um PRAZO processual do Astrea no lugar, PRESERVANDO o prazo_id') and immediately differentiates the operation from delete-and-recreate, which is the most likely wrong sibling behavior. An agent can distinguish this from astrea_prazo_criar, astrea_prazo_excluir and astrea_prazo_cancelar without opening any schema.

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?

Gives an explicit prohibition with a reason ('NÃO exclua e recrie: isso gera um id novo e apaga as tarefas vinculadas'), states the partial-update contract ('Informe ao menos um campo; o que você omitir fica como está'), and routes to siblings for inputs (prazo_id from astrea_prazo_criar or a DEADLINE in astrea_agenda; responsible_id via astrea_responsaveis).

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