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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses the return payload contents, that gravar=true with arquivo_json persists into the file itself, that it refuses when the audit has failures, and that downstream contract/scenario changes invalidate the approval. These are substantive behavioral traits that annotations do not carry.

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 precondition, then behavior and constraints in a compact block. Every sentence carries information; formatting packs a lot into a few clauses, though slightly dense.

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?

With no output schema, the description compensates by describing the returned aprovacao object, and it covers the precondition, persistence behavior, and invalidation for a 5-parameter tool with nested objects. Complete enough to invoke correctly, though it does not detail especificacao's structure (delegated to calculo_modelo_json).

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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics: the arquivo_json + gravar=true interaction and the mapping of por/observacoes into the returned aprovacao object. That goes beyond what the per-field schema descriptions convey.

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 action on a specific resource: registering the user's approval of the interpretation plan, and it names the artifact it produces (contrato.aprovacao). It is clear enough to distinguish from calculo_plano_interpretacao and calculo_validar, but it never explicitly names those siblings, so it lands short of a 5.

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 gives a hard precondition (use ONLY after the user approved the plan in the conversation) plus refusal and invalidation conditions (refuses if the audit has failures; later changes to contract or scenario invalidate approval). No alternative tool is explicitly named for the not-yet-approved case, so it stops short of 5.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real context beyond them: it explains that jornadas are generated from the programação/escala respecting feriados, férias e faltas, that columns are created, and that the operation is effectively one-shot (button disappears once cards exist). It does not detail what happens to existing apurações or permission requirements, so it falls just short of full disclosure.

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 precondition, then the operational steps and the redo caveat; every sentence carries information. It is a dense single paragraph that could be broken into steps, but there is little waste.

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, non-idempotent mutation with no output schema, the description covers preconditions, side effects, and the return value ('Devolve o quadro mensal apurado'). It omits only peripheral details like required state/permissions, so it is essentially complete for correct 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 100%, so the schema already documents id_calculo, regerar, and the vinculos array down to nested verba/cartao/tipo. The description restates the vinculos concept (ligar verbas às colunas, quantidade ou divisor importados do cartão) but adds no syntax or format beyond the schema, so the baseline 3 applies.

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 (apurar/salvar cada apuração) and resource (cartão de ponto / jornadas de um cálculo já no PJe-Calc), and names the concrete artifacts it produces (colunas Hs EXT, Hs Trabalhadas, Hs Noturnas). This clearly separates it from siblings like cartoes_para_jornadas and calculo_regerar_ocorrencias.

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 precondition ('Para um cálculo já no PJe-Calc com apurações de cartão de ponto cadastradas') and an explicit when-not/how-to-undo rule ('O botão Apurar só existe enquanto o cálculo não tem cartões; para refazer, exclua os cartões em Cartão de Ponto > Visualizar Cartão'). An agent knows exactly when this tool applies and how to repeat it.

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

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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this ('Não altera os cálculos') while adding a non-obvious behavioral rule: equality of totals does not substitute equality of occurrences. That methodology caveat is genuine context beyond the annotations, though return shape/limits aren't detailed.

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 core comparison purpose, then layered methodology, then a docs pointer. The sentences are dense but each carries real information (occurrence-level diffing, the causal factors, the gross-to-net bridge), so little is wasted despite the length.

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?

With no output schema and 7 params including a nested object, the description carries the return-value burden and does reasonably: it spells out the comparison layers and the residual/residue notion. It stops short of describing the exact response shape or remediation of found differences, but is sufficient to call 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?

Schema description coverage is 100%, so the schema already documents every parameter including the nested referencia_manual structure. The description adds only high-level framing (the two-sided id/arquivo model, same base-date constraint), which is useful but not meaningfully beyond 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?

States a specific verb+resource (compare a calculation against a reference account) and immediately scopes it: same base date, each side being a PJe-Calc id or an exported .PJC. It also enumerates the comparison layers (occurrences then the verba/gross-to-net bridges), which cleanly separates it from siblings like calculo_validar or calculo_liquidar.

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 explains how to populate each side (id vs arquivo vs referencia_manual) and points to pjecalc://docs/modulos/referencia, so usage is implied and constructible. However, it never states when to reach for this over calculo_validar or other comparison-adjacent tools, so no explicit when/when-not guidance is given.

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

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

With annotations only declaring readOnly=false/idempotent=false/destructive=false/openWorld=true, the description carries the real behavioral burden and delivers: side effects (starts PJe-Calc, imports, regenerates ocorrências, writes -PRONTO.PJC/-LIQUIDADO.PJC/-RELATORIO.pdf), a documented state machine ('estado': rascunho, aceito_pelo_aplicativo, calculado, simulacao, auditado), gate conditions ('bloqueiosDeEntrega'), and the caveat that delivery review is always human. That is substantive disclosure beyond 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?

It is front-loaded with the recommended-flow statement, but the body is a very long, run-on, jargon-heavy sentence with three dense clauses about liquidation, returns, and data-contract gating. Almost every clause carries real information, yet the wall-of-text structure makes it hard to scan.

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 high-complexity orchestration tool with no output schema and a nested free-form especificacao object, the description supplies what an agent needs: the full execution sequence, the returned fields and state values, the produced artifacts, the blocking/precondition rules, and the delimiter of automatic vs. human responsibility.

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 100%, so the schema already explains every parameter (destino, iniciar, liquidar_em, exportar_final, ignorar_tabelas, atualizar_tabelas, etc.), making 3 the baseline. The description adds only a little param-linked meaning, mainly that liquidar_em triggers a TEST liquidation and the downstream verification set; it does not clarify the especificacao object contract beyond pointing at calculo_modelo_json.

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 composite action ('Fluxo completo e recomendado para montar um cálculo') and enumerates the exact steps performed (validate spec, generate .PJC, import, apurar cartão de ponto, ligar verbas, regerar ocorrências, devolver número). It is unmistakably distinct from atomic siblings like calculo_gerar_pjc or calculo_importar_pjc. It does not, however, name any sibling explicitly to steer the choice, so it stops short of a 5.

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 signals this is the recommended end-to-end flow and specifies conditional behavior: with liquidar_em it also liquidates and verifies; under a data contract it refuses to generate while a mandatory document is missing, auditing failed, or the interpretation plan is unapproved. No explicit 'when NOT to use / use X instead' statement is given against the ladder of single-step siblings.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description is not carrying that burden. It adds genuinely useful behavior instead: every item passes the same gates (documents, map, title, approval), and one item's error does not abort the rest — critical for a batch tool. It stops short of disclosing rate limits, ordering guarantees, or whether partial results are rolled back.

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?

Three sentences, front-loaded with the core action before the use cases and the return semantics. Dense with parentheticals but each clause carries information the agent needs; nothing is padding.

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?

With no output schema, the description quite properly covers the return shape (per-item calculation number, state, totals, failures, plus consolidated gross/net totals of settled items). Combined with the error-isolation note and the parallel gates, this is close to complete for a 5-parameter batch tool; only the source of specifications (especificacoes vs arquivos_json) is left entirely to the schema.

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 100%, so the schema already explains liquidar_em, arquivos_json, especificacoes, ignorar_tabelas and atualizar_tabelas. The description nods to the list of specifications and the per-debtor period but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 in the batch domain: it runs calculo_criar for every specification in a list, and explicitly distinguishes itself from the single-item sibling by naming it. The parenthetical use cases (litisconsórcio ativo, responsabilidade subsidiária/sucessiva, cenários) tell an agent exactly what "batch" means here.

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 scenarios enumerated (one per claimant, one per debtor, multiple scenarios) make the trigger condition clear and imply that a single calculation should go through calculo_criar instead. There is no explicit when-not-to-use statement, but the routing context is strong enough that an agent can choose correctly.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: it is iterative ('repita a cada rodada'), emits a request text ('pedido'), and signals completion via 'completa: true', plus points to a doc resource.

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?

Dense but front-loaded with the key role ('PRIMEIRO PASSO'), then scope, then usage modes, then the loop condition. Every sentence carries weight, though the parenthetical document enumeration is somewhat long.

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 6-parameter, nested-object tool with no output schema, the description explains the return (a 'pedido' text) and the completion signal ('completa': true). It is largely complete, though the exact shape of the returned request is only indirectly described.

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 coverage is 100%, so baseline is 3. The description goes further by grouping parameters by mode: admissao/demissao/parcelas/documentos_recebidos apply 'sem especificação' while especificacao/arquivo_json are the alternative path, clarifying inter-parameter relationships the schema only hints at.

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 'PRIMEIRO PASSO de todo cálculo' and then states the concrete verb+resource: it determines which documents a case requires, checks month coverage, lists user-only questions, and returns a ready 'pedido' text. This clearly positions it against document-validation and planning siblings like catalogo_validar_documentos and calculo_plano_interpretacao.

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 explicitly states two entry modes (with a specification, 'mesmo parcial', or before it using quick answers such as parcelas deferidas and dates) and the loop condition ('Repita a cada rodada até completa: true'). It gives clear context but names no explicit sibling alternatives or when-not-to-use cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real substance beyond that: the operation is IRREVERSÍVEL and requires the exact string "SIM, EXCLUIR" as confirmation.

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?

Three short sentences, front-loaded with the action, then the irreversibility warning, then the backup pointer. Nothing is redundant.

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 two-parameter destructive delete with no output schema, the description covers the only things an agent needs: the exact confirmation value, the irreversibility, and the safe alternative. Nothing material 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 coverage is 100% and both parameters (id_calculo, confirmacao) are documented in the schema, including the exact confirmation string. The description's mention of confirmacao repeats rather than extends the schema, so the baseline 3 applies.

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?

Specific verb ('Exclui') plus resource ('um cálculo do PJe-Calc') and even the UI path (Operações > Excluir). It is clearly distinguishable from siblings like calculo_criar, calculo_atualizar and calculo_exportar_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?

Gives explicit prep guidance: call calculo_exportar_pjc first if you want to keep the calculation, and states the mandatory confirmation token. It does not spell out conditions under which deletion should be avoided, but the routing advice is clear.

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

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

The annotations already declare that this is a non-read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds useful behavioral context beyond the annotations by specifying that the output is an actual .PJC file and explaining the intended workflows, though it does not disclose overwrite behavior or permission requirements.

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?

A single, front-loaded sentence that leads with the verb and resource, then adds the UI path and use cases without redundancy. Every clause earns its place.

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?

Given the low complexity, complete schema coverage, and annotations that cover the mutation and safety profile, the description is nearly complete for correct invocation. It omits only minor details such as overwrite behavior and what the tool returns, which is a small gap for a file-export operation with no output schema.

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 100%, and the schema already explains both parameters, including the default destination folder and the meaning of id_calculo. The description does not add any parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 (Exporta), a specific resource (um cálculo do PJe-Calc), and a specific output format (.PJC), while also naming the UI path (Operações > Exportar). It clearly distinguishes itself from the sibling calculo_ler_pjc, which performs the inverse read operation.

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 explicitly states three concrete use cases: backup, sending to third parties, and checking against calculo_ler_pjc. However, it does not state when not to use the tool or present a full alternative decision rule, keeping it just short of a 5.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), yet the description adds real behavioral context beyond them: it drives the interface screens, PJe-Calc converts parcels into a liquidated calculation on save, it exports a .PJC, and with "execucao" it mutates the copy via calculo_atualizar. This discloses side effects the annotations alone would not.

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 core action, then proceeds through process, field groups, docs reference, and export/update behavior. Dense but each clause carries information; the long enumerated lists are the only mild bloat.

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 tool that automates a GUI and takes an underspecified nested object, the description is fairly complete: it names the screens, the field groups, an example reference (calculo_modelo_json "externo") and a docs URI. With no output schema, it still describes the side effects on disk and on the existing copy.

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 coverage is nominally 100%, but the calculoExterno object is only typed as additionalProperties:{} with no inner structure, so the schema explains almost nothing about its contents. The description compensates by enumerating the expected fields (processo, dataBase, parametros, creditos, descontos, outrosDebitos, debitosReclamante, execucao), adding meaning the schema lacks.

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+resource ("Cria no PJe-Calc um Cálculo Externo") and immediately differentiates it as the approved account computed outside the app (perito, contadoria, acordo), distinguishing it from the sibling regular calculation creators. An agent can identify the purpose and its niche without opening a 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?

The description conveys the scenario (external, homologated calculation consolidated at the base date) but does not explicitly state when to prefer this over calculo_criar/calculo_importar_pjc or any exclusion conditions. Usage is implied through the scenario rather than stated as routing guidance.

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

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

Annotations declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is already covered. The description adds real behavioral context beyond that: it works offline without PJe-Calc running, and when 'apuracaoCartaoPonto' is present it also writes a <arquivo>.mcp.json sidecar with post-import steps. It does not state overwrite behavior for the destino path.

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?

Four dense sentences, front-loaded with what the tool produces, then workflow and side-effect details. Each sentence carries information, though the import/regerar instructions could be tightened slightly.

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?

With no output schema and nested objects, the description compensates by describing the produced artifacts (.PJC file and optional .mcp.json) and the required post-import workflow. It is nearly complete, missing only overwrite/error behavior for the destination path.

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 coverage is 100% and each parameter has its own description, so the schema already carries the load. The description mentions the 'apuracaoCartaoPonto' behavior (a field inside the specification rather than a top-level parameter) and the identity of the specification source, adding only marginal semantics.

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 a specific verb+resource: it generates the .PJC file (the official PJe-Calc export/import format) from a specification. It also distinguishes itself from siblings by explaining that it does not require PJe-Calc to be open and by naming calculo_importar_pjc as the downstream tool.

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?

Clear context is given: no need for PJe-Calc to be open, the file imports into any PJe-Calc 2.16.x, and after importing you must use Verbas > Regerar or run calculo_importar_pjc. It names the alternative tool and the condition that selects it, though it never explicitly contrasts against calculo_criar or calculo_exportar_pjc.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description still adds real behavioral detail beyond them: it runs post-import steps from <arquivo>.mcp.json when present, regenerates occurrences, and returns the calculation number and pendências. It does not mention failure modes or what happens on a partial import.

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?

A single, front-loaded sentence that leads with the core action and appends side effects and return value in order of importance. Dense but coherent; every clause carries operational meaning, though the sentence is long enough to benefit from light restructuring.

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?

No output schema exists, but the description compensates by naming the return payload (número do cálculo e pendências). It covers the side-effect chain and the mcp.json conditional. Missing only error/partial-failure behavior and explicit preconditions for a fairly complex multi-step import.

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 100%, so the schema already documents all four parameters including defaults. The description restates the default behavior of regerar ("regera as ocorrências (padrão)") but adds no syntax, format, or edge-case meaning beyond the schema. Baseline 3 applies.

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 ("Importa") and resource (a .PJC file), plus the destination context (PJe-Calc em execução) and the file's provenance (generated by the MCP or exported from another PJe-Calc). An agent can distinguish this from siblings like calculo_gerar_pjc, calculo_exportar_pjc, or calculo_ler_pjc without opening their schemas.

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?

Usage context is implied by "no PJe-Calc em execução" and the described post-import workflow, but there is no explicit when-to-use vs alternatives guidance (e.g., why choose this over calculo_ler_pjc or calculo_gerar_pjc). No exclusions or prerequisites beyond the implicit requirement that PJe-Calc be running.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered externally. The description adds only that the output is a human-readable summary, saying nothing about failure modes (missing/invalid .PJC path) or output format, so it adds modest value on top of structured data.

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?

Two sentences, front-loaded with the core purpose, then the usage context. The long enumeration of summary contents is dense but earns its place because no output schema exists to describe the return.

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?

With no output schema, the description compensates by listing what the readable summary contains, which is exactly what an agent needs to decide the tool is appropriate. It stops short of stating the output medium (plain text vs structured) or error behavior for unreadable files.

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?

There is a single parameter with 100% schema description coverage ('Caminho do .PJC'), so the schema already carries the meaning and the baseline of 3 applies. The description adds no path format, extension, or relative-vs-absolute guidance.

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+resource ('Resumo legível de um .PJC') and enumerates the exact domain content the summary covers (partes, históricos salariais, verbas, FGTS, correção e juros). It implicitly separates itself from generate/import/export siblings via 'conferir um arquivo gerado ou entender um cálculo exportado', but never names an alternative tool, so it falls short of a 5.

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?

'Serve para conferir um arquivo gerado ou entender um cálculo exportado' gives an implied context of use, but there is no explicit when-not guidance and no named alternative (calculo_importar_pjc, calculo_modelo_json) for an agent that needs to load rather than merely inspect a file.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false for this mutation. The description adds useful context beyond them: the operation is normally user-driven, and it discloses what the call returns (bruto, líquido, total devido pelo reclamado, valores por verba), which matters since no output schema exists.

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?

Two sentences, front-loaded with the action and the returned data, with the usage caveat second. No filler, though the usage caveat could be tightened into a cleaner when/when-not clause.

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 side-effecting tool with no output schema, the description compensates by naming the returned totals, and the rich schema covers all parameters including the table-refresh and regeneration flags. What is missing is any note on whether tables must be current (only implied via ignorar_tabelas) and how errors surface.

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 100%, so all seven parameters (regerar, regional, data_liquidacao, ignorar_tabelas, acumular_indices, atualizar_tabelas, id_calculo) are already documented in the schema, including the enum semantics and defaults. The description does not add parameter-level meaning beyond that, so the baseline 3 applies.

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?

Specific verb+resource ("Liquida o cálculo no PJe-Calc"), names the exact UI path (Operações > Liquidar), and states the return payload (Resumo do Cálculo totals). An agent can distinguish it from siblings like calculo_relatorio or calculo_regerar_ocorrencias without opening the 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?

"Normalmente quem liquida é o usuário; use para conferir o resultado ou quando ele pedir" gives an explicit triggering condition and implicitly warns against routine use. It states when to call but does not name alternative sibling tools for adjacent needs.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description adds that the return is documentation plus tested examples, which is useful content-scoping context, but discloses nothing further about output size, filtering via "exemplo", or formatting.

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?

A single front-loaded sentence with the verb and resource first, followed by a short imperative directive. The long parenthetical field enumeration is informative but slightly bloated; still, every element earns roughly its place.

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 read-only documentation tool with no output schema, the description sufficiently conveys what is returned (field coverage and examples) and when to call it. Nothing essential is missing, though it never explains the relationship between the "exemplo" selector and the full-document default.

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 100% and both parameters (exemplo enum, somente_exemplo boolean) are documented in the schema itself. The description's field list describes the returned document, not the two input parameters, so it adds little parameter-level meaning beyond the schema. Baseline 3 is correct.

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 ("Devolve") and resource (the complete documentation of the JSON describing a calculation), and enumerates the covered fields plus tested examples. Clear on its own, but it does not name the closest siblings (e.g., catalogo_enums or db_esquema) to disambiguate which reference/schema tool to pick.

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?

"LEIA ANTES de montar um cálculo" gives an explicit when-to-use trigger tied to the assemble-a-calculation workflow. It does not, however, name alternatives or state when not to use it (e.g., when a python/JSON spec is already in hand).

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds real value by clarifying that it opens the calculation but explicitly does NOT liquidate (a state-change boundary) and by classifying output as errors (which block liquidation) vs alerts.

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?

A single dense sentence followed by a short clause, front-loaded with the action and constraint. Quoted UI labels are slightly heavy but justified since they pin the exact screen and panel.

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?

No output schema exists, and the description does name the two result categories (erros and alertas) and what errors mean. It stops short of describing the shape of the returned list or behavior when the calculation is unavailable, which is a minor gap.

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?

Only one parameter (id_calculo) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax, format, or value guidance beyond what the schema already provides, making the baseline 3 appropriate.

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+resource: opens the calculation in PJe-Calc and reads the "Pendências do Cálculo" panel of the Liquidar screen, explicitly "SEM liquidar". This distinguishes it from calculo_liquidar, but the sibling calculo_validar also exists and the description's claim to be "a validação oficial do aplicativo" does not disambiguate between the two.

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?

Clear context: use this to inspect pendencies without performing the liquidation. The "SEM liquidar" qualifier implicitly tells the agent not to use this when actual liquidation is wanted (calculo_liquidar), but it never names the alternative or states explicit exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the output is markdown, it must be shown to the user for approval, and it returns the contract hash to be approved. No contradiction with 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?

Front-loads the core action and the required approval step, and the long content enumeration is informative rather than redundant. Slightly dense, but every clause identifies real plan content or a real workflow constraint.

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?

With no output schema, the description appropriately discloses what is returned (markdown plan plus the contract hash). The nested especificacao parameter is delegated to calculo_modelo_json for its format, and the approval workflow is spelled out, leaving little missing for correct 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 coverage is 100%, so both parameters are already documented in the schema. The description's 'a partir do contrato e da especificação' loosely implies inputs but does not map to arquivo_json vs. especificacao or explain their mutual exclusivity/alternative nature, so it adds little beyond the schema. Baseline 3 is appropriate.

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+resource ('Gera o plano de interpretação legível (markdown)') and enumerates the exact contents the plan covers (processo/fase, matriz do título, parcelas, critérios, eventos, premissas, pendências). The workflow framing ('peça a aprovação ANTES de calcular') makes it clearly distinct from calculo_aprovar_plano and the calcular-family siblings.

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 explicit sequencing guidance: show the plan to the user and request approval BEFORE calculating. This is clear context for when to invoke it, though it does not name the sibling tools (calculo_aprovar_plano, calculo_gerar_pjc) that carry out the next steps.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context (it is the home-screen recent list, not an arbitrary query) and the returned fields, but says nothing about ordering, limits, or empty-state behavior.

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?

A single, front-loaded sentence with no waste. The nested quotation of the UI label is slightly noisy but does not obscure meaning or bloat the text.

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 zero-parameter, read-only listing tool with annotations covering safety, the description covers purpose and output fields adequately. The absence of an output schema means some details (result structure, ordering, count limits) remain unspecified, leaving a modest gap.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate, per the baseline-4 rule. The parenthetical field list adds minor value about what the (parameterless) call yields but is not required.

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 ("Lista") and resource ("Cálculos Recentes" / aba Abrir Cálculos Recentes do PJe-Calc), and names the fields shown. It distinguishes the tool from sibling readers like calculo_ler_pjc or pjecalc_paginas, though the reliance on a UI label rather than a functional description slightly muddies it.

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?

No explicit when-to-use, when-not, or alternative routing is provided. The agent can only infer that this browses recently opened calculations; nothing tells it how this differs from calculo_ler_pjc or calculo_pendencias in a selection scenario.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds real value beyond that by disclosing WHAT is at risk: manually edited occurrences are overwritten unless manter_alteracoes=true, with regeneration of everything as the default. This concretely explains the destructive behavior rather than just repeating the hint.

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?

Three tight fragments: operation and scope first, then the usage trigger, then the parameter effect. No filler sentences; the destructive/parameter caveat is front-loaded where the agent will see it.

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 mutation tool with annotations covering the safety profile and no output schema, the description supplies the missing pieces an agent needs: when to call it, that it is destructive, and how to preserve manual edits. Only minor gaps remain (no prerequisite/permission notes, no mention of what regeneration returns).

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 100%, so both parameters are already documented, and the description's note on manter_alteracoes largely restates the schema ('padrão: regera tudo'). The UI-path phrasing ('selecionar todas, inclusive reflexos ativos') implies an internal scope but does not clarify parameter syntax. Baseline 3 is appropriate when the schema carries the parameter detail.

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 names a specific action ('Regerar' ocorrências das verbas) and describes the scope ('selecionar todas, inclusive reflexos ativos'), which is more than a restatement of the title. An agent can understand it regenerates calculation-item occurrences. It does not explicitly differentiate itself from siblings like calculo_atualizar or calculo_validar, so it stops short of a 5.

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?

'Necessário depois de importar ou de mudar parâmetros' gives a clear trigger condition for when to invoke the tool. There is no explicit statement of when NOT to use it and no named alternative, but the usage context is unambiguous.

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

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

Annotations already cover safety and idempotency, and the description adds important behavior: default full report, HTML returning text plus extracted totals, and PDF writing a file. It does not discuss error cases or what happens if the calculation is not liquidated, but the main side effect is disclosed.

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 front-loaded with purpose and default behavior, then lists report sections and standalone types. It is dense and long, but most of the length is useful domain detail rather than 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 a report-generation tool with no output schema, it sufficiently explains defaults, output formats, file-writing behavior, and available report types. Minor gaps remain around the exact returned total structure and failure modes, but an agent can 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?

Schema coverage is 100%, so the schema documents the parameters, but the description adds meaningful detail by explaining the default COMPLETO value and enumerating the available standalone report types beyond the schema's generic string array. It does not add much about max_caracteres or arquivo_pdf beyond what the schema already says.

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 first sentence states a specific verb and resource: generate the PJe-Calc report for an already-liquidated calculation. The 'já liquidado' constraint distinguishes it from calculation-mutation and liquidation siblings, though no sibling is named explicitly.

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 explains the default COMPLETO behavior, the standalone report types, and when HTML versus PDF is appropriate. It does not explicitly exclude sibling tools such as calculo_ler_pjc or calculo_exportar_pjc, so usage routing is clear but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial extra context: the two validation layers, the concrete audit checks (payment used twice, salary outside validity, work during leave, duplicate base), the 'não verificado' fallback, and the fact that it returns errors/warnings/summary without side effects.

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 key scope statement, and the detailed audit-check enumeration is informative rather than redundant. It is dense and somewhat long, but every clause conveys a distinct validation behavior.

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?

With no output schema and a nested-object parameter, the description carries the burden well, explaining the audit field, the error/warning distinction, and the summary of what will be assembled. Return-shape detail is at a useful high level rather than fully specified.

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 100%, so both parameters (arquivo_json and especificacao) are already documented in the schema. The description does not add syntax or mutual-exclusivity detail beyond noting the spec format source, so baseline 3 applies.

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 (validate) and resource (calculation specification), and immediately delineates scope by declaring it does NOT generate a file nor touch PJe-Calc, which cleanly separates it from siblings like calculo_gerar_pjc and calculo_criar.

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 opening clause 'SEM gerar arquivo nem tocar no PJe-Calc' establishes the pre-generation validation context and implicitly routes the agent away from generation tools. However, it never names the alternative (e.g., calculo_gerar_pjc) or states an explicit when-not condition, so a slight gap remains.

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

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

The annotations already declare this as a read-only, idempotent, non-destructive operation, so the description does not need to cover safety. It adds meaningful behavioral detail: the exact output field returned and a rich list of validations (missing days, odd markings, overlapping/impossibly long shifts, interjornada under 11h, invariant times under Súmula 338).

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 two dense but well-structured sentences with no filler: first the input forms and return value, then the validation checks. Every clause earns its place, and the most important information is 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?

For a nested-input, no-output-schema transformation tool, the description gives enough context to invoke it: required day markings, accepted shapes, output field, and validation behavior. It could say more about how validation issues are surfaced in the return object, but the safety profile is already covered by annotations.

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 coverage is 100%, so the baseline would be 3, but the description adds semantic detail not present in the schema: it enumerates the accepted occurrence values (FOLGA, FERIAS, FALTA, ATESTADO, FERIADO, DSR) and shows the three accepted day-record shapes. It does not add much for the periodo or dias_sem_marcacao parameters, but those are already described 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 states a specific transformation: it receives daily time-card markings and returns apuracaoCartaoPonto.jornadas, then lists the anomalies it reports. This is far more than a restatement of the title, but it does not explicitly differentiate itself from the sibling calculo_apurar_cartao_ponto tool.

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 description explains what the tool does but gives no explicit when-to-use or when-not-to-use guidance, and it never names a sibling as an alternative or prerequisite. Usage is only faintly inferable from the input/output description, so the agent must guess how it fits into the broader calculo workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful domain context (source table, and how the returned code is consumed) but says nothing about result volume, pagination, or ordering. With annotations carrying the behavioral load, a 3 is appropriate.

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?

It is a single dense sentence with no filler, and the core resource definition is front-loaded ahead of the integrating detail. Efficient, though the parenthetical is slightly parenthetical-heavy rather than crisp.

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 simple read-only catalog lookup with annotations covering safety, a 1-param schema at full coverage, and no output schema, the description supplies what an agent needs: what the catalog contains and where the code is consumed. It omits the shape/fields of returned entries, but for a catalog of this simplicity that gap is minor.

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 100% and the single 'filtro' parameter is documented in the schema as 'Parte do nome ou do código do assunto'. The description adds no further parameter detail (no matching semantics, no wildcard/normalization notes), so the baseline 3 for a fully-covered schema applies.

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 identifies the specific resource: 'Assuntos da Tabela Processual Unificada do CNJ cadastrados no PJe-Calc', which tells an agent this is the CNJ-subject catalog. The parenthetical tying the code to 'verbas[].personalizada.assuntoCnj' sharpens its purpose further. It lacks an explicit verb (list/look up) and does not directly differentiate itself from sibling catalogs like catalogo_verbas, so it stops short of a 5.

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 parenthetical ('código para verbas personalizadas: verbas[].personalizada.assuntoCnj') implies the key use case — retrieving the code to fill a custom-verba field — which is useful implied guidance. However, there is no explicit when-to-use statement, no when-not-to-use, and no routing against catalogo_verbas or other catalog siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered elsewhere. The description's only additional behavioral value is disclosing the return payload (id and descrição), which matters because no output schema exists, but it says nothing about ordering, completeness of the table, or freshness.

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?

One tightly packed sentence with no filler; the resource is stated before the usage context, so it is front-loaded. The nested parenthetical about alíquotas do empregador makes the second half slightly harder to parse than a split sentence would be, but nothing is wasted.

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?

With no output schema, the description correctly compensates by naming the returned fields (id e descrição), and the annotations carry the safety and idempotency profile. What remains missing is what the tool does when called without a filter and whether the catalog is exhaustive or paginated.

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?

There is a single optional parameter, 'filtro', and the schema already documents it at 100% coverage as 'Parte da descrição ou o id.' The description adds no matching semantics, case sensitivity, or behavior when the filter is omitted, so the baseline of 3 applies.

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 names a specific resource (atividades econômicas da tabela do PJe-Calc) and states exactly what is returned (id e descrição), which lets an agent tell it apart from unrelated tools. It stops short of an explicit verb and does not distinguish itself from the many other catalogo_* siblings, so it is clear but not fully differentiated.

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 parenthetical ties the catalog to a concrete destination field (contribuicaoSocial.atividadeEconomica), which implies when the lookup is needed, but there is no explicit when-to-use/when-not-to-use statement and no routing to or away from the sibling catalogo_* tools. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds domain context (which calculation fields these values feed) but says nothing about return shape, whether the catalog is static or version-dependent, or whether it can be empty. With annotations carrying the behavioral load, this is adequate but thin.

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?

A single dense sentence with no filler, and the most important anchor ('Colunas criadas por Apurar Cartão de Ponto') is front-loaded. The nested parenthetical is compact rather than wasteful, though the list of categories makes it slightly hard to scan.

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, so the description must at least frame what comes back; it enumerates the categories of content but never indicates the return structure or cardinality. Combined with the absence of any 'when to use this vs. another catalogo' routing, an agent can call it but cannot fully anticipate the response.

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?

The tool takes zero parameters, so the baseline of 4 applies. The description goes slightly beyond by anchoring the catalogue's values to specific consumer paths (verbas[].quantidade.cartao, divisor.cartao), which tells the agent where the returned names are meant to be used.

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 names the concrete contents of the catalog (columns created by 'Apurar Cartão de Ponto', overtime criteria, fill-ins, shift types, night hours) and the exact field paths that consume the names (verbas[].quantidade.cartao, divisor.cartao). This makes the resource identifiable within the catalogo_* family, though it never states a retrieval verb like 'retorna'/'lista' and never names a sibling it should be preferred over (e.g. catalogo_verbas, catalogo_enums).

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?

Usage is only implied: the reader infers the tool should be consulted to obtain valid values for apuracaoCartaoPonto fields. There is no explicit when-to-use, when-not, or preference relative to sibling catalogs such as catalogo_verbas or catalogo_enums, which is especially important given how many catalogo_* tools exist.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond the annotations by disclosing the argument-dependent branching (listing enum names vs entity enum fields), which an agent needs to invoke it correctly.

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?

Two tightly written sentences, examples front-loaded, no filler. The reader gets the resource and both modes immediately.

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 two-param read-only lookup with no output schema, the description conveys what is returned at a useful level (enum names, entity enum fields). A note on the actual return shape would close the last gap, but nothing essential 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 coverage is already 100% with both params documented, but the description adds meaning the schema lacks: it clarifies that omitting 'nome' lists enum names, and that 'classe' scopes results to an entity's enum fields, with worked examples.

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 clear verb+resource: it retrieves the accepted enum constants for PJe-Calc fields, with concrete examples (IndiceMonetarioEnum, JurosEnum, etc.). This distinguishes it from other catalog tools like catalogo_verbas or catalogo_municipios, though the differentiation is implicit rather than stated.

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 description explains the two invocation modes (no argument → enum names; 'classe' → enum fields of an entity), which effectively tells the agent how to steer the call. However it does not say when to prefer this tool over sibling catalogs or what prerequisites exist.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that this is static PJe-Calc catalog data tied to calculo.pontosFacultativos, but says nothing about return format, ordering, or pagination. Adequate but not rich.

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?

Two dense sentences with no filler, and the core resource definition is front-loaded before the ancillary note about calculo.pontosFacultativos. Efficient for the amount of information conveyed.

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 read-only catalog lookup with no output schema and fully documented parameters, the description explains what data comes back and how it relates to the calculation. Only the return shape and filtering behavior are left implicit, which is a minor gap.

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 100%, so the schema already documents uf, tipo, filtro and municipio, establishing the baseline of 3. The description restates the tipo F/P meaning and adds the F/E/M abrangência taxonomy, which actually refers to holiday records rather than a parameter and omits the schema's third enum value 'B'. Marginal added value.

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 names the exact resource (feriados tipo F and pontos facultativos tipo P from PJe-Calc) and its scope (national/state/municipal). An agent can tell it apart from sibling catalogs like catalogo_municipios or catalogo_verbas. It never states an explicit verb such as 'list/retrieve', but the catalog nature is clear.

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?

No guidance on when to call this versus sibling catalogs, and no prerequisites. The only contextual hint is that pontos facultativos are marked in the calculation by name in calculo.pontosFacultativos, which describes downstream use rather than when to invoke this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds that the data comes from the PJe-Calc table and that the search is a lookup, but it doesn't describe return format, pagination, or any other operational behavior.

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?

A single sentence with no wasted words, and the core action and purpose are front-loaded. Every clause earns its place.

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 low-complexity catalog lookup with rich annotations and 100% schema coverage, the description is largely complete. It omits any mention of return values, which is a minor gap given there is no output schema.

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 100%, so the schema already documents both parameters. The description mentions 'nome/UF/id', which slightly exceeds the schema (no id parameter), but adds no syntax or format detail beyond what the schema provides; baseline 3 applies.

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 ('Procura') and resource ('municípios'), plus the source table and the exact output fields it supports ('calculo.uf' and 'calculo.municipio'). This distinguishes it from the many other catalogo_* siblings that cover verbas, assuntos, feriados, etc.

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 gives a clear usage context: use this tool to fill calculo.uf and calculo.municipio. It does not list exclusions or alternatives, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds real value by disclosing the data source (read via modelos_atualizar with alvo "catalogos") and the precondition that PJe-Calc must be stopped, plus the same-state/municipality validity constraint. It omits pagination or result-size behavior.

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?

A single dense paragraph whose purpose is front-loaded; each sentence carries actionable information (source, integration, constraint, fallback). The comma-heavy clause stacking slightly hurts scanability but nothing is truly wasted.

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?

Given the tool's cross-tool dependencies (modelos_atualizar, verbas[].base), lack of an output schema, and no required params, the description covers return fields, downstream usage, precondition, validity constraint, and fallback. It is complete enough for an agent to call it correctly, with only minor gaps around edge cases.

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 coverage is 100%, so both parameters (uf, nome) are already documented in the schema; the description mentions uf/município in the context of results rather than clarifying the filter parameters. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ("Lista") and resource (the "Pisos Salariais" and "Vale-transporte" tables of the user's PJe-Calc), and enumerates the returned fields (id, nome/linha, UF, município, período). It is immediately distinguishable from sibling catalogs like catalogo_cartao_ponto.

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?

Explains how the returned id is consumed (verbas[].base { tipo: "SALARIO_DA_CATEGORIA", piso: id } / { tipo: "VALE_TRANSPORTE", ... } and valorPago), which defines the tool's purpose in the workflow, and even gives a fallback when the table is absent (HISTORICO_SALARIAL). It does not, however, name explicit sibling alternatives or exclusion conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds one genuine behavioral detail beyond that: it does not merely validate, it 'devolve o dígito CNJ correto' (returns the corrected digit). It says nothing about behavior on invalid input or error reporting, keeping it at a middling 3.

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?

A single front-loaded sentence with the action first and the rationale in a parenthetical. No filler, though the parenthetical is slightly conversational given the schema already handles formatting.

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 read-only three-parameter tool with no output schema, the description carries the return-value burden but only covers the CNJ case ('devolve o dígito CNJ correto'), leaving unspecified what is returned for CPF and CNPJ or how invalid inputs are reported. Adequate but incomplete.

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 100%, and each of the three parameters (cpf, cnpj, numero_processo) is documented in the schema with accepted formatting. The description maps loosely onto the same concepts but adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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 verb 'Confere' plus the resources 'dígitos verificadores' and 'dígito CNJ' state a specific validation action, and the title names CPF/CNPJ, so the scope is clear. It stops short of distinguishing itself from any sibling, but no other sibling is a document validator, so an agent can place it accurately.

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 clause 'o PJe-Calc recusa número de processo com dígito errado' implies the use case (validate a number before feeding it to PJe-Calc), but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, openWorld=false, non-destructive, so safety is covered. The description goes beyond that by describing the returned content (each verba's default fields plus its reflexos list), which is useful since there is no 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?

Two sentences, front-loaded with what the tool returns, followed by a practical naming instruction. The parenthetical field list is dense but informative rather than wasteful.

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 read-only, single-optional-parameter catalog with no output schema, the description adequately conveys the returned structure and the canonical-name contract. Minor gaps (result ordering, meaning of an unfiltered call) are inferable from the schema's zero required parameters.

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?

There is only one parameter and schema description coverage is 100%, so the schema already documents 'filtro' with examples. The description adds no filtering syntax or semantics of its own, so the baseline of 3 applies.

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 names a specific resource (the "Expresso" launch verbas of PJe-Calc) and enumerates its default parameters and reflexos list, so an agent knows exactly what this catalog returns. It lacks an explicit verb but the resource scope is precise enough to separate it from generic catalog siblings.

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?

Usage is implied: this is a lookup for canonical verba/reflexo names, reinforced by 'Use os nomes exatamente como aparecem aqui'. However, there is no explicit when-to-use vs alternatives (e.g., catalogo_enums) and no note on whether filtro is optional or what an unfiltered call returns.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds genuinely new context: an automatic backup is taken on writes and the URL change can silently repoint to a different database. That is exactly the kind of consequence detail annotations cannot convey.

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?

Two tight sentences: the dual-mode rule is front-loaded and the risk warning closes it. No filler or restated name/title.

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 3-param tool with no output schema and full annotation coverage, the description supplies mode behavior, backup side-effect, and the URL caveat. Only the shape of the read result is left unstated, which is minor given no output schema exists.

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 100%, so the three parameters are already documented in the schema. The description maps them to url/username/password and adds no format or syntax detail beyond that, so the baseline 3 applies.

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 resource (jdbc/pjeCalcDS DataSource from META-INF/context.xml) and both verbs (read vs. alter) conditioned on argument presence. The resource is distinct from the config_* siblings (ports, memory, token), though no sibling is named explicitly.

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 no-args/with-args rule gives explicit when-to-use guidance for the two modes and the ATENÇÃO note warns about the URL consequence. It stops short of naming alternatives (e.g. config_ler or db_* tools) for related tasks.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations cannot express: the files are ISO-8859-1 encoded, which matters for decoding the result. It does not say whether missing files error or return empty, but the addition is real.

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?

Two short sentences, no padding, and the encoding note is placed last where it belongs. Efficient, though the filename list duplicates the enum and arguably consumes space the description could have spent on usage guidance.

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 single-enum read tool with no output schema, an agent knows what to pass and roughly what comes back via 'Conteúdo de um arquivo'. It never states the return shape (raw text vs structured) or error behavior for an invalid/missing file, which is the remaining gap.

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 100% and the single parameter is a closed enum, so the schema fully documents the input. The description's file list largely repeats the enum values rather than adding format or selection guidance, so baseline 3 applies.

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 title plus description make clear this retrieves the contents of a PJe-Calc configuration file, and the enumeration of specific filenames (server.xml, context.xml, catalina.properties, etc.) pins the scope. It is a noun phrase rather than a verb+resource statement, but the resource is unmistakable. It does not differentiate itself from siblings like config_portas or config_memoria, which also touch configuration.

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?

There is no statement of when to use this tool rather than the many sibling config_* tools (config_portas, config_memoria, config_token, config_datasource), nor any prerequisite or exclusion. Usage must be inferred purely from the tool name and the file list.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds genuinely useful context beyond them: an automatic backup is created, values are in MB, and a restart is required to apply. Missing detail on whether the change is reversible beyond the backup, but the disclosure is strong.

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?

Two tightly packed sentences, front-loaded with the mode switch, then backup/unit/restart facts. Zero filler; every clause earns its place.

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 dual-mode config tool with no output schema, the description covers both the read return content (Xms/Xmx) and the write side effects (backup, restart needed). An agent has everything needed to invoke it correctly in either mode.

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 coverage is 100% and the schema already documents xms/xmx with units and ranges. The description adds the mapping that these args become -Xms/-Xmx in the two .bat files, giving file-level meaning beyond the schema's abstract 'Heap' phrasing.

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 (reads/writes Xms/Xmx JVM heap) and elegantly distinguishes its two modes: no-args reads, with-args mutates. An agent can tell exactly what it does versus the many config_* and pjecalc_* siblings.

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 tells the agent when each mode applies (no args = read; with args = write), which is a clear usage split. It does not name alternative tools, but the arg-presence trigger is unambiguous enough that the lack of sibling routing is minor.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds valuable specifics: only active connectors are modified, comments are preserved, an automatic backup .mcp-backup-<timestamp> is created, and the launcher may auto-switch ports if HTTP is busy. These details go well beyond the safety flags.

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?

Three sentences, front-loaded with the core read/write behavior, followed by implementation notes. The final sentence about the launcher is contextually relevant but slightly tangential, keeping it from a 5.

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?

With no output schema, the description still covers the essential behavior for both modes, the file affected, backup, and preservation of comments. Combined with full schema coverage and clear annotations, an agent has enough 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?

Schema description coverage is 100%, and the schema documents each parameter (ajp, http, shutdown) with defaults and ranges. The description repeats the parameter names but adds no new semantic detail (e.g., format, interaction), so baseline 3 applies.

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?

It explicitly states dual behavior: no args reads current ports; with args modifies http/ajp/shutdown in tomcat/conf/server.xml. The verb (lê/altera) and resource (ports in server.xml) are specific, and the dual mode distinguishes it from generic config siblings.

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 description clearly indicates when to use no-argument mode versus argument mode, which is the primary usage decision. However, it does not name alternative tools (e.g., config_ler) or state when not to use this tool, so it falls short of a 5.

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

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

Annotations declare destructive=true and idempotent=true; the description goes further by revealing that a write replaces the token in BOTH .bat files, that an automatic backup occurs, and that the token guards the /servico/rest/* endpoints via an Authentication: Base64(token) header. This adds meaningful context about scope and side effects beyond 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?

Three dense sentences that are front-loaded with the two modes before adding security context. Every sentence carries information, though the header-format detail is slightly tangential for a config tool.

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 single-parameter tool with no output schema, the description covers both modes, the side effect and its backup mitigation, and the security role of the token. Return format is only implied ('mostra o token atual'), leaving a minor gap.

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 coverage is 100% (baseline 3), and the description adds real meaning by showing novo_token triggers the write mode and is applied to both files with an automatic backup, going beyond the schema's bare 'Novo token (opcional)'.

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 dual verb+resource: read the current REST services token, or replace it, and names the exact config key (seguranca.pjecalc.tokenServicos). This clearly separates it from siblings like config_portas or config_memoria, so an agent can disambiguate without opening the 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?

It explicitly explains the two invocation modes: with no argument it shows the current token; with novo_token it replaces it in both .bat files. The condition selecting each mode is unambiguous, though no alternatives or exclusions (e.g., what to use for other config) are named.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real context beyond that: the DB is locked while PJe-Calc runs, the copy must happen with the app stopped for consistency, and pjecalc_parar is the required prerequisite. This is exactly the kind of operational constraint annotations cannot express.

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 the action, then the consistency caveat, then the locking rationale and the remediation step. The rhetorical question is slightly unusual but tight, and every sentence contributes.

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 simple file-copy operation with no output schema, the description covers the critical prerequisite (app stopped) and the tool's mechanism. It could note what confirmation/result the caller receives, but nothing essential for correct invocation 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 100% and the single parameter 'arquivo' already documents its default pattern, so the schema carries the parameter semantics. The description adds no syntax or format detail beyond it, making the baseline 3 appropriate.

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 precisely: 'Copia o arquivo .dados/pjecalc.h2.db byte a byte', which makes the physical-file-copy nature unambiguous and implicitly distinguishes it from the SQL-dump sibling db_backup_sql. It does not, however, name that sibling explicitly, so differentiation relies on inference.

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 a clear precondition and when-to-use rule: only run with the app stopped, and it names pjecalc_parar as the required prior step. It stops short of explicitly contrasting with db_backup_sql, so the choice between physical and SQL backup is left to the agent.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false. The description adds genuinely useful context beyond them: the mechanism (org.h2.tools.Script), the ~9 MB size, and critically the constraint that the database stays locked while PJe-Calc runs, requiring pjecalc_parar first. It does not state whether an existing target file is overwritten.

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?

Three short sentences, purpose front-loaded, then the prerequisite. The implementation detail about the JRE/org.h2.tools.Script is slightly more than the agent needs but is compact and earns some informational value.

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 one-parameter backup writer with full schema coverage and annotations covering the safety profile, the description supplies the key operational caveat (stop the app) and output expectations. Missing only edge-case behavior such as overwrite/error handling on the destination path.

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 100% and the single 'arquivo' parameter is fully documented in the schema, including its default. The description adds no format or path syntax beyond that, so the baseline 3 applies.

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+resource ('Gera backup completo (schema + dados ...) em SQL') and explicitly names the output format and approximate size (~9 MB), which distinguishes it from the sibling db_backup_arquivo. It does not, however, explicitly call out that sibling as the alternative, so the differentiation is by implication rather than direct contrast.

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 a clear precondition and names the tool that satisfies it: 'Encerre o aplicativo (pjecalc_parar) antes de usar as ferramentas de banco.' That is actionable routing. It stops short of an explicit when-to-use vs. db_backup_arquivo or db_restaurar comparison.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description still adds meaningful behavior: results are capped at max_linhas rows, and the tool will fail unless the PJe-Calc application is stopped first. It also shows a concrete query shape, which sets expectations for input format.

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 action and read-only nature, followed by helper-tool guidance, an example, and the lock prerequisite. Every sentence carries information, though the inline SQL example adds some length and the 'somente leitura' phrasing partially repeats the annotation.

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 two-parameter read tool with rich annotations but no output schema, the description covers action, input guidance, row cap, and the critical operational prerequisite. It does not describe error behavior or result column formatting, but nothing essential for a correct invocation 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 100%, so the baseline is 3; the description adds a little by clarifying that max_linhas is the row cap on the returned result and by providing a sample SELECT that demonstrates the sql parameter format. It does not explain default/limit interactions beyond what the schema states.

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: executes a SELECT on the H2 database in read-only mode. It separates itself from the write-capable sibling db_executar by declaring 'somente leitura', though it never names that sibling as the alternative for writes. An agent can identify the tool's job without opening the 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?

Explicitly routes the agent to db_tabelas/db_esquema to discover table/column names before querying, and gives a hard precondition: PJe-Calc holds the database locked while running, so pjecalc_parar must be called first. This is exactly the when-to-use / when-not-to-use guidance that prevents failed calls.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description adds a genuinely useful behavioral constraint not in the annotations: the H2 database is locked while PJe-Calc runs and must be released first. It does not mention error behavior for unknown table names.

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?

Two sentences, zero waste: the purpose and returned fields are front-loaded, and the blocking constraint follows. Every sentence earns its place.

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?

With no output schema, the description usefully enumerates what is returned (name, type, nullability, default), and the locking precondition is stated. A read-only single-parameter tool needs little more; only failure behavior for invalid table names is unaddressed.

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 100% and the single 'tabela' parameter is documented with concrete examples (TBSELICDIARIA, TBVERBA, TBCALCULO). The description's field list refers to the returned columns rather than adding meaning to the parameter, so the baseline 3 applies.

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 resource and return shape: the columns (name, type, nullability, default) of one H2 table. An agent can distinguish this from db_tabelas (listing tables) or db_consultar (querying rows) by inference, but no sibling is named explicitly, so it falls just short of a 5.

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 gives a concrete operational precondition — the PJe-Calc keeps the database locked while running, so the app must be stopped (pjecalc_parar) before using database tools. That is real when-to-use guidance, but it does not contrast this tool with db_consultar/db_tabelas or state when schema inspection is preferable.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: discloses the mandatory confirmation token, that a .h2.db backup is taken first, that direct inserts desynchronize Hibernate sequences causing 'Registro duplicado' failures, and that the DB file is locked while PJe-Calc runs. That is exactly the consequence-level context annotations cannot carry.

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 the danger and the confirmation requirement, then the failure-mode warning, then the locking prerequisite — every sentence carries operational weight despite the length.

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 destructive, no-output-schema mutation tool this covers prerequisites (stop PJe-Calc), safety (backup, confirmation), and the correct alternative path, leaving nothing an agent needs before calling it.

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 coverage is 100%, so the baseline is 3; the description adds real meaning by explaining what kinds of SQL are dangerous and why (sequence advancement), not just restating the parameter names. The sql parameter itself still gets no format/syntax guidance beyond 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?

States a precise verb (executa) and resource (banco H2) plus the exact statement classes (INSERT/UPDATE/DELETE/DDL), which cleanly separates it from read-only siblings like db_consultar and backup siblings like db_backup_arquivo.

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 explicit when-not guidance (não use para criar/alterar cálculos; use calculo_criar) and a hard prerequisite (encerre o aplicativo via pjecalc_parar antes de usar as ferramentas de banco). An agent cannot mistake the correct route.

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

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

Adds significant operational detail beyond annotations: the underlying RunScript mechanism, mandatory confirmation value, automatic backup creation, and PJe-Calc database lock behavior. Annotations cover destructive and idempotent hints, but the description supplies the concrete safety and sequencing requirements.

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 three tightly written sentences, front-loading the action, then the destructive warning and prerequisites, with no wasted content.

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?

Given the destructive nature, no output schema, and rich annotations, the description covers the critical requirements: confirmation value, pre-backup behavior, execution method, and the need to stop the application first. An agent has enough information 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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds useful context that the SQL file should be generated by db_backup_sql and reiterates the exact confirmation string, though it does not provide new syntax details beyond 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?

States a specific verb and resource: restore the database by executing a SQL file generated by db_backup_sql via org.h2.tools.RunScript. This clearly distinguishes it from siblings like db_backup_sql and db_executar.

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 warns that the operation is destructive, requires the exact confirmation string, automatically backs up the current .h2.db, and instructs the agent to stop PJe-Calc via pjecalc_parar before using database tools. This provides clear preconditions and usage context.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable operational context beyond the annotations: the embedded H2 database file path, the fact that the application locks the database while running, and the required prerequisite to stop the app before using database tools.

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 two compact sentences, front-loading the table scope and then the critical operational prerequisite. Every sentence carries useful information with no wasted wording.

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 no-parameter, read-only listing tool with no output schema, the description is complete enough. It states what is listed, where it comes from, the scale and categories, and the essential prerequisite for use.

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?

The tool takes no parameters, and the schema is an empty object. With zero parameters and full schema coverage, the baseline score is 4; the description appropriately adds no parameter-level detail because none exists.

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 specifies the exact resource and scope: tables of the PUBLIC schema in the embedded H2 database, including the file path and categories of tables. This is clear and specific enough to distinguish it from siblings that query or execute SQL, though it does not explicitly name those alternatives or use a direct verb like 'list'.

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 gives a clear prerequisite: PJe-Calc locks the database while running, so the application (pjecalc_parar) must be stopped before using database tools. This is strong context for when and when not to call the tool, but it does not explicitly point to sibling alternatives such as db_esquema or db_consultar.

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

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

Adds substantial context beyond the annotations: writes files to disk (consistent with readOnlyHint=false), operates without external programs, keeps only the largest image per page and drops small logos, and reports unsupported encodings (CCITT, JBIG2, JPEG 2000) in an 'avisos' field. These are concrete behavioral traits an agent could not derive from the schema or 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?

Purpose is front-loaded and every sentence carries information (format handling, page selection, warnings, no-OCR caveat). The parentheticals and semicolon-dense clauses make it slightly heavy to scan, but nothing 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 a file-writing tool with no output schema, the description covers where files go (referenced in schema), what each file represents, and how conversion failures surface via 'avisos'. It is nearly complete, though it does not state the naming/return convention of the written files explicitly.

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 100%, so the parameters are already documented, and the description adds only the page-image selection semantics (largest image is usually the full page). The 'paginas' range syntax and 'destino' default are left entirely to the schema, so baseline 3 is appropriate.

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 in the first clause ('Grava em arquivos as imagens das páginas de um PDF'), then specifies the per-format behavior (JPEG as-is, others PNG). It is clearly distinguishable from siblings like documento_inventario and documento_texto, both of which it references or implicitly contrasts with.

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 routes the agent: 'Use nas páginas que documento_inventario marca sem texto', naming the sibling call that produces the precondition. It also clarifies an edge case of that precondition (the PJe signature stamp does not count as text) and states what the tool cannot do (no OCR), leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description nonetheless adds meaningful context beyond them: that text-less pages are scans which must be VIEWED as images, that it emits a suggested contrato.documentos plus a contrato.leitura skeleton, and the classification rule for every page (used / irrelevant with reason / illegible with request).

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 the verb and output contents before workflow hints, and the semicolon-separated list keeps a fairly information-dense block readable. The nested parentheses (especially the long contrato.leitura clause) make it heavier than it needs to be, but nothing is truly redundant.

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?

With no output schema, the description carries the return-value burden and does so thoroughly: it names the output artifacts, enumerates the inventory fields, states the page-classification requirement, and places the call in the workflow (etapa 2) with a link to further module docs. An agent has enough to invoke it correctly without opening anything else.

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 100%, so pasta, prefixo, arquivos and processo are already documented (including the default "D" prefix). The description references contrato.processos only indirectly via "números de processo citados" and adds no syntax or selection guidance beyond the schema, so the baseline 3 applies.

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?

Opens with a specific verb and resource ("Lista cada arquivo") and immediately enumerates the exact per-file payload (sha256, page count, pages with/without text, probable type, cited case numbers), which cleanly distinguishes it from siblings like documento_texto and documento_imagens that operate on already-inventoried documents.

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 explicit timing guidance ("Use logo que receber os documentos (etapa 2)") and points at supporting documentation (pjecalc://docs/modulos/leitura). It stops short of naming when NOT to use it or an alternative tool, so it's clear context without exclusions.

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

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

Annotations already cover read-only/idempotent/non-destructive, yet the description still adds non-obvious behavior: pages lacking own text are flagged, the PJe signature stamp does not count as text, and output order may not follow the visual column order. It does not mention that output can be truncated by max_caracteres (default 60000), a relevant behavioral caveat.

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?

Three tight sentences: purpose first, then the scan/alternative caveat, then the ordering warning. No filler; each sentence carries a distinct, actionable fact.

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?

With no output schema, the description still conveys the shape of the result (text per page, with a scanned-page marker) and the two failure modes an agent must handle (scanned pages, column misordering). Nothing essential for correct invocation 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 100% (arquivo, paginas, max_caracteres all documented in-schema), so the baseline is 3. The prose adds no per-parameter detail, only the caveat to verify text against the page.

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 with scope: extracted text page by page from a PDF (or text file). It also implicitly distinguishes itself from documento_imagens by routing scanned/no-text pages there, so an agent can separate the two without opening either 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 the use case (locate excerpts, check numbers), an explicit exclusion (pages without their own text are scanned; the MCP does no OCR), and names the alternative tool (documento_imagens) for that case. When-to-use and when-not-to-use are both covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: it computes and returns fgts.operacoes, per-competência deposits, and two reconciliation checks (sum = balance; competências without deposits).

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?

A single dense sentence, front-loaded with the input contract then the outputs and checks. Every clause earns its place, though the inline tuple notation makes it slightly harder to parse than separated sentences.

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, so the description must carry the return-value burden, and it does: it names the produced entities and the two conferências. Nothing critical for correct invocation appears 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 coverage is 100%, so the schema already documents all four parameters. The description echoes the lancamentos shape ({competencia, data, valor, tipo}) but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 transform: it receives FGTS analytic-statement entries plus final balance and returns fgts.operacoes, deposits per competência, and reconciliations. The verb/resource pair (extrato -> operações) is unambiguous and no sibling overlaps it.

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?

Usage is implied by the naming of input sources and output targets, but the description never states when to use this versus alternatives or what prerequisites exist. With many sibling tools present, an explicit 'use this to convert an FGTS statement extract' cue would help.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail beyond them: it verifies proventos − descontos = líquido, flags missing competências, proventos not absorbed into a history, and months lacking a rubrica, and names the return shape (historicosSalariais with _origem, contrato.remuneracoes). This is rich, non-redundant disclosure.

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 what is received, then the checks, then what is returned — a logical order — and every clause carries information. It is a single dense multi-clause sentence, which slightly hurts parseability but wastes little.

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?

With no output schema and nested-object inputs, the description compensates by naming both returned artifacts (historicosSalariais ocorrências with _origem, contrato.remuneracoes vigências) and the validation semantics. Nothing an agent needs to invoke 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 100%, so periodo, holerites and historicos are already documented in the schema. The description restates the field groupings but adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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 transformation (transcrição de holerites -> históricos salariais) with concrete verbs (recebe, confere, devolve) and enumerates exactly which fields flow in and out. An agent can distinguish it from adjacent 'X para Y' siblings (extrato_para_fgts, trct_para_pagamentos) because the resource pair is named precisely.

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 description implies the use case (converting transcribed payslips into salary histories with validation) but never states when to prefer this tool over alternatives or any prerequisites/exclusions. Usage is inferable from the transformation framing rather than spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds real context beyond them: the verbas path creates a temporary cálculo, exports, builds the library and then deletes the temporary. It stops short of stating what is overwritten if the models already exist.

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?

Two sentences, front-loaded with the action and then the invocation guideline, with the two modes parenthetically scoped. Dense but no padding; the nested clauses are long but each carries operational detail.

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 one-parameter mutation tool with full annotation coverage and no output schema, the description covers action, both modes, preconditions and timing. It only lacks failure/overwrite consequences, which limits it below a 5.

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 coverage is 100% and the enum values are already documented, so the baseline is 3. The description still adds meaning by tying each enum value to its runtime precondition (PJe-Calc running vs stopped) and to the different data sources (Expresso verbas vs H2 municipality/CNJ/holiday tables).

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 (Refaz) and resource (os modelos usados pelo gerador a partir da instalação), then splits it into two clearly named modes ("verbas" vs "catalogos") with distinct behavior. An agent can distinguish this rebuild-models tool from sibling update tools like tabelas_atualizar 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 explicit when-to-use ("Use após atualizar o PJe-Calc ou sincronizar tabelas") and, more valuably, the operational precondition per mode: verbas requires PJe-Calc running, catalogos requires it STOPPED. It does not name alternative sibling tools to prefer instead, so it falls short of the top mark.

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

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

Annotations declare the safety profile (non-read-only, non-destructive, idempotent, closed-world), so the description's burden is lighter. It adds real value by disclosing the prerequisite state (app running) and the browser selection behavior, going beyond what the annotations state.

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?

Two short sentences with no waste; the primary behavior is front-loaded and the prerequisite is appended compactly. Every clause earns its place.

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 simple launcher with no output schema, the description covers the action, the browser selection, and the prerequisite state. It does not address failure behavior (e.g., what happens if the app is not running) or any confirmation returned, but that is a minor gap given the tool's simplicity.

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 coverage is 100%, so both parameters (pagina, firefox_portatil) are already documented in the schema. The description mentions the browser choice, which loosely maps to firefox_portatil, but adds no syntax, defaults, or format details beyond the schema, so the baseline of 3 applies.

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 and resource: opening the PJe-Calc web interface in the default browser (or bundled portable Firefox). This is clear and distinct from sibling tools like pjecalc_paginas or pjecalc_status, though it never explicitly names or contrasts those siblings.

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 gives one prerequisite — 'Requer o app em execução' (the app must be running) — which is genuinely useful context. However, it offers no guidance on when to use this versus related tools such as pjecalc_paginas or pjecalc_status, leaving usage largely implied.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing that the payload includes a service token (sensitive) and spans many subsystems. It does not say whether the data is read from disk or requires a running installation, nor any cost/latency implications of gathering all of it.

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?

A single sentence that front-loads the core claim ('Identidade completa da instalação') followed by a compact enumeration of contents. Every item listed is informative; the list is long but each element is a distinct returned field, not 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?

With no output schema, the description must carry the return shape, and it does so by enumerating the major fields, including the token and TRT URLs. Annotations cover the safety profile and there are no parameters. The only missing piece is the static-vs-live source of the data and its relationship to the config_* siblings.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema is empty and 100% covered by definition, and the description correctly implies a parameterless snapshot call.

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?

It states a clear resource (the installation's identity) and enumerates exactly what that means: jar version, modules, stack, ports, DataSource, JVM params, token, TRT URLs. An agent knows precisely what comes back. It does not, however, differentiate from near-identical siblings such as config_portas, config_token, config_datasource, config_ler or pjecalc_status, which appear to overlap heavily.

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?

There is no when-to-use guidance and no exclusions. Given siblings like config_memoria, config_portas, config_token and pjecalc_status that plausibly return subsets of the same data, an agent has no way to know whether this is the aggregate overview or whether the narrower tools should be preferred.

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

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

Goes beyond the annotations (idempotentHint, destructiveHint=false) by disclosing the up-to-3-minute wait, that Tomcat is started as the official launcher, that no window/browser opens in headless mode, and the resulting port/URL. It does not state what happens if the service is already up or what a failure looks like.

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 action and its timeout, then the mode semantics, then the follow-up URL. Dense and mostly waste-free; the trailing localhost sentence is marginally useful but slightly beyond the tool's own scope.

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?

No output schema and a single optional parameter, so the description carries the burden and does so adequately: what starts, how long it waits, the modes, and the endpoint exposed. It omits how to confirm readiness afterward (pjecalc_status) and the return shape.

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 coverage is 100% (baseline 3), but the description adds real meaning to the enum values — "sem-navegador" is explained as launching Tomcat without a window, "normal" as equivalent to iniciarPjeCalc.bat — which the terse schema text does not convey.

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 ("Inicia o PJe-Calc") and disambiguates the two launch modes with concrete behavior for each. It does not, however, distinguish itself from nearby siblings like pjecalc_abrir_interface or pjecalc_status, which an agent must sort out on its own.

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?

"sem-navegador (padrão) ... ideal para o agente" gives clear guidance for choosing a mode, but there is no guidance on when to pick this tool over the sibling launch/status/info tools, nor any stated prerequisites (e.g. is the app already running?).

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

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is partly covered. The description adds real behavior beyond that: the ordered discovery strategy (PJECALC_HOME, saved choice, running instance, parent folder, common directories) and the fact that "pasta" persists a choice while "procurar_de_novo" forgets it. No contradiction with 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?

Front-loaded with the primary purpose (which installation is in use and how it was found), followed by per-parameter behavior. The parenthetical list of search locations is long but informative; otherwise the text is tight.

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 compensates by explaining what is reported (the installation in use plus the discovery method). For a two-parameter, zero-required tool this is essentially complete, with only minor gaps around failure behavior when nothing is found.

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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema lacks: "pasta" selects and persists an installation for future runs, and "procurar_de_novo" clears the saved choice. These side effects are not visible from the schema alone.

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+resource: it shows which PJe-Calc installation the MCP is currently using and how it was found. This is clearly distinct from siblings like pjecalc_status and pjecalc_info, and an agent can tell what the tool returns without opening the 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 explicit conditions for both parameters: use "procurar_de_novo" when the folder was moved, and "pasta" to persist a user-chosen installation. It also instructs the agent to ask the user when multiple installations exist. It does not name an alternative sibling tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the log location and the filtering behavior of somente_erros, but says nothing about rotation, file count, encoding, or how the raw lines are returned.

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?

Two compact sentences with the resource identified first and the practical trigger in the second. No padding or redundant restatement of the title.

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?

With annotations covering safety and no output schema required, the definition tells the agent where the logs live and when to apply the error filter — enough to call it correctly. It could still note the default volume of lines returned per file.

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 100%, so all three parameters (linhas, arquivo, somente_erros) are documented in the schema, including the default of 60 and the 500 maximum. The description only restates the meaning of somente_erros, adding no syntax or format detail beyond 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 gives a specific verb and resource: reading the last lines of the Tomcat/MCP logs under tomcat/logs. It is unmistakably the only log-reading tool among the siblings, though it never explicitly contrasts itself with any of them.

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 names a concrete trigger: when an operation returns "Erro Interno no Servidor", use somente_erros=true to see only exceptions and GRAVE lines. No alternative tool or exclusion is mentioned, but the when-to-use context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value beyond that by characterizing the output as a 'complete map' of .xhtml pages and tying it to the follow-up open step, though it omits anything about output format details.

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?

Two tightly written sentences: the first front-loads the purpose and scope, the second gives the follow-up action. No filler or redundancy.

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 zero-param listing tool with annotations covering the safety profile and no output schema, the description is nearly complete: it says what is returned (paths to webapp pages) and how to use them. Minor gap in not describing the exact return shape, but adequate.

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?

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies a no-argument, list-everything operation rather than suggesting filters.

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 precise verb+resource: it maps/list the .xhtml pages of the webapp, and adds concrete examples (calculos, índices, INSS, IRPF, FGTS, custas, pagamento, cartão de ponto). This clearly separates it from sibling tools like pjecalc_abrir_interface, which consumes the returned path rather than producing the map.

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 second sentence explicitly routes the agent to the next action: use pjecalc_abrir_interface with the returned path to open each page. This gives clear context for when the tool is used, though it does not state exclusions or when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely useful behavior beyond that — the orderly Tomcat shutdown when MCP-started (with the H2 database closing correctly) versus killing the java process like the launcher would. It could go further by warning about data-loss risk in the non-MCP/forced path.

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?

Dense but well front-loaded: the action comes first, then the two conditional branches in a single sentence. Every clause carries information, though the nesting of conditions makes it slightly heavier than necessary for a one-parameter tool.

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 simple stop tool with one optional flag, no output schema, and destructive/idempotent annotations already present, the description covers the important runtime behavior in both branches. Only the return/error behavior when nothing is running is left implicit, which is acceptable given idempotentHint=true.

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 100% and the single optional 'forcar' flag is documented in the schema itself ('Encerra o processo java diretamente'). The description does not mention the flag or explain how an explicit force interacts with the two shutdown paths it describes, so it adds nothing over the schema — baseline 3.

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 and resource ('Encerra o PJe-Calc') and is unambiguously the opposite pole of the sibling pjecalc_iniciar, so an agent can route between start/stop/status 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?

It explains what happens in each shutdown path but never says when the agent should call this versus alternatives such as pjecalc_status (to check whether PJe-Calc is even running) or whether calling it when already stopped is a no-op. No when/when-not guidance or prerequisites are given.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the closing 'Não altera nada' merely restates that. Beyond the structured data, the description adds real behavioral value: it explains that the tool reads the log to produce a diagnosis (e.g. out-of-memory) and includes remediation guidance when the app is down, which tells the agent what a non-responding result actually contains.

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?

A single front-loaded sentence with the reported fields listed first and the failure-path behavior second; every clause carries information. The only soft spot is the trailing 'e o que fazer', which is vague about whether remediation advice is data in the response or a directive to the agent.

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, so the description must convey return content, and it does: process state, port, reachability, version, database, and log-based diagnosis. Adequate for a zero-parameter read tool; it could be marginally stronger by stating the response shape (structured fields vs. free text) since no output schema exists.

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?

The input schema has zero parameters, so the baseline is 4 and there is nothing further the description could clarify. No parameter semantics are needed or missing.

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 enumerates exactly what the tool reports: Java processes, HTTP port, whether the application responds, version and database, plus log-derived diagnosis when it does not respond. That is a concrete verb+resource picture an agent can act on. It stops short of naming a sibling (e.g. pjecalc_logs or pjecalc_info) to distinguish overlapping diagnostic data, so it is clear but not fully differentiated.

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?

Usage is only implied: an agent infers 'call this to check whether PJe-Calc is up and why it is not.' There is no explicit when-to-use/when-not, and no routing to pjecalc_logs for raw logs or pjecalc_iniciar/pjecalc_parar for lifecycle actions, which are the obvious neighbors for the 'what to do' part.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that these are 'exemplo' reference files but does not describe return shape or listing behavior. Against annotation-covered reads, a 3 is appropriate.

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?

Two compact sentences; the resource definition is front-loaded and the intended use follows. Every sentence earns its place. Slightly less than 5 because the category list is a bit long but it is informative rather than 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 a single-parameter, annotation-covered read tool with no output schema, the description is sufficient: it says what is inside the files and why to read them. The only minor gap is that it does not restate that an empty argument lists available templates, but the schema covers that.

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 100%, and the schema already explains the path format and the empty-string listing behavior. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 resource ('Conteúdo dos arquivos CSV de exemplo') and enumerates the categories (cartão de ponto, jornada, faltas, férias, histórico salarial), so an agent immediately knows what it returns. It does not name a sibling it overlaps with, but no sibling provides this template content, so no differentiation is strictly needed.

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 gives an explicit use case: 'Use como referência para gerar arquivos de importação.' This tells the agent when the tool is valuable. However, it offers no when-not guidance or alternative tools, keeping it short of a perfect score.

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