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

Adds real context beyond annotations: batch runs in a single call but is internally chunked, processing is asynchronous with effects appearing within seconds, and 'remover' removes the tag from the case without deleting the tag itself. The non-destructive removal note is valuable and consistent with destructiveHint=false.

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-loads purpose and the sibling distinction, then bullets the mechanics. Dense but every line earns its place; minor redundancy between the headline 'Aplica ou remove' and the per-action bullet.

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 2-param mutation with no output schema, it covers prerequisites (tags must pre-exist), async timing, batch semantics, and non-destructive removal — everything an agent needs to invoke it correctly.

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 carries the full burden and delivers: case_ids are process ids (see astrea_processos) and accept multiples; tag_ids are tag ids (see astrea_etiquetas) and accept multiples. Both required params are explained with discovery pointers.

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 concrete verb+resource ('aplica ou remove etiquetas em PROCESSOS, EM LOTE') and differentiates from astrea_tarefa_etiquetar for tasks. However, the name and flattened action say 'remover' while the description leads with 'Aplica ou remove', creating a slight mismatch about whether this instance applies or removes tags.

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?

Explicitly names the use case (classify/hygiene the portfolio, mass-tagging hundreds of cases), points to the correct sibling for tasks (astrea_tarefa_etiquetar), and states the prerequisite that tags must already exist in Astrea. Nothing is left to inference.

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