Contar dias úteis entre datas

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is low; the description still adds real context beyond them. It discloses the boundary convention (start excluded, end included), that non-counted days are returned with reasons, and that the computation is local ('Cálculo local'), implying no network call and deterministic results.

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 core question and the counting convention, then calendar scope, then output shape, then the local-computation note. Every clause carries information an agent would otherwise have to guess.

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 sketches the return ('Lista os dias que não contaram e por quê'), and it defers tribunal validation to tribunais_cobertos, which is the right move. It is nearly complete for a six-parameter read-only calculator, missing only explicit interaction rules between 'tribunal', 'materia' and 'comarca'.

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 83% and both enums ('materia', 'calendario') are documented in the schema, so the baseline is 3. The description restates the calendar-mode defaults already present in the schema and adds nothing new about 'de'/'ate' formats, 'comarca' holiday lookup, or how 'materia' interacts with 'tribunal'.

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 ('Quantos dias úteis há entre duas datas') and pins the counting convention (excludes start date, includes end date), which is the main ambiguity for this kind of tool. It does not distinguish itself from siblings like somar_uteis/feriados/calcular_prazo by name, so an agent must still infer which of the date-math tools 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?

Implied guidance only: the 'calendario' clause explains that 'forense' is the default when a tribunal is given and 'nacional' when it is not, which nudges selection, and it points to tribunais_cobertos for valid siglas. There is no explicit when-to-use-this-instead-of-somar_dias_uteis or calcular_prazo statement and no stated exclusions.

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