fluig_deadline_calc

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

With no annotations, the description carries the full burden and does well: it warns about the 60× seconds-vs-minutes trap between the API and the process model's deadlineTime and directs the agent to duracaoEmMinutos for auto-conversion. It does not state whether the call is purely computational or writes anything, nor what the returned value/unit is, which is a meaningful remaining gap for a tool mentioning 'gravado'.

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 front-load the purpose, then the mode list, then the unit hazard, then the per-mode required params. No filler; every clause either selects a mode or prevents a specific mistake.

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?

Covers the hard parts for an 8-parameter, three-mode tool: mode selection, conditional requirements, and the unit trap. The notable omission is the result itself — there is no output schema and the description never says what is returned (a timestamp? seconds? which unit?), which an agent needs in order to use the answer.

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 88%, so the baseline is 3, but the description adds information the schema does not encode: the conditional required-parameter sets per mode (the schema only marks modo and env as required). It also clarifies the seconds-vs-minutes semantics of duration vs duracaoEmMinutos, which prevents a concrete 60× error.

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 ('Calcula prazo em HORÁRIO ÚTIL pelo calendário do servidor') and immediately enumerates the three operating modes (duracao | fim | inicio). No sibling in the fluig_* list does deadline math, so it is trivially distinguishable from the process/dataset/form tools.

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 mode-selection rule is explicit: 'Obrigatórios: duracao = startDate+endDate · fim = startDate+segundos · inicio = endDate+segundos', telling the agent exactly which parameters each mode demands. It does not say when this tool should be preferred over, e.g., computing dates manually or reading deadlineTime from a card, so it stops short of full when/when-not guidance.

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