Atualizar cálculo homologado (execução: pagamentos e eventos)

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

Beyond the annotations, it discloses that the tool writes events into a COPY of the calculation, leaves the source unchanged, runs the PJe-Calc 'Liquidar Atualização' with rateio/imputação, performs validation checks against MSG rules, and returns the Resumo da Atualização plus '-ATUALIZADO.PJC'. This is rich behavioral context that an agent could not infer from the schema or annotations alone.

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 purpose is front-loaded, and every sentence carries useful information (fields, docs, validation, copy behavior, return artifacts). However, the dense single-paragraph style with many parentheticals makes it less scannable than it could be, so it is not maximally concise.

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 write tool with no output schema, the description covers the input preconditions, the execution-phase behavior, the internal liquidation step, and the returned artifacts. It also directs the agent to pjecalc://docs/modulos/execucao and calculo_modelo_json for full field details, making it adequately complete.

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?

Although schema coverage is 100%, the nested 'execucao' object is only a free-form map in the schema; the description compensates by enumerating its key subfields (dataAtualizacao, pagamentos with credit/recolhimento splits, honorários, multas, pensão, custas, precatório/RPV, cobrarEncargosIrpf) and pointing to concrete examples. This adds material meaning beyond the structured definition.

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 states a specific verb (atualiza) and resource (cálculo liquidado) and scopes it to the execution phase, with the required 'execucao' block. It distinguishes this from the liquidation step by noting it runs 'Liquidar Atualização' internally and returns '-ATUALIZADO.PJC', so an agent can tell it apart from calculo_liquidar and calculo_importar_pjc.

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?

It clearly states the phase context (execution phase) and input prerequisites: a liquidated calculation supplied either as an exported .PJC or an id_calculo. It does not explicitly name when-not scenarios or alternative sibling tools, so it falls short of full routing guidance.

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