tm

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description reconciles this by making clear the tool also performs a read-style listing by default. Beyond that it adds little: it does not disclose the preview-then-confirm workflow that governs the write path (only the schema's cf parameter hints at it), nor permission or side-effect details for logging hours.

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 resource label first and the two modes clearly parallel-structured; no filler. It is perhaps slightly too compressed for a nine-parameter dual-mode tool, 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 nine optional parameters, two modes, and a write path, the description covers the mode split and defaults but omits the approval/confirmation prerequisite that is central to correct invocation, relying on the schema to surface it. With no output schema, it also says nothing about what listing returns or how logged entries are echoed.

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 acao, quem, periodo, data, horas, and cf thoroughly, including the confirmation-code approval requirement. The description largely restates the defaults that are already documented per-parameter, adding only the 'meus' mapping to quem='eu' implicitly.

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 (Horas) and two distinct operations — listar lançamentos and lançar horas em um work package — with their defaults, so an agent understands the tool's dual nature. It does not distinguish the tool from its cryptic siblings (ls, find, new, up), and the name 'tm' itself conveys nothing, so the description carries all the identification burden.

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?

Defaults are stated for both modes ('padrão: meus, esta semana' for listing, implying lancar otherwise), which implies when each branch applies. However, there is no explicit guidance on when to choose this tool over the many sibling tools, nor any statement of prerequisites or exclusions for the write mode.

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