Work hours / time card

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

Adds real behavior beyond the readOnly/idempotent annotations: an end time at or before the start is treated as an overnight shift, there is a cap of 6 shifts per day (the schema only caps totals at 42), and overtime is applied daily first and then weekly. These are non-obvious rules that change how the tool computes results, though no error handling or limits on the pay output are described.

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 front-loaded block that leads with the core purpose and then layers in shift rules, rounding, overtime and pay without repetition. Despite the density, every clause carries a distinct rule; even the reference URL is a single trailing token.

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 input rules and describes the outputs it produces (per-shift/day/week totals in h:mm and decimal, plus pay), which matters since there is no output schema. It leaves minor gaps such as invalid-time behavior and how currency interacts with pay, but nothing an agent needs to form a valid call 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%, so the baseline is 3, but the description goes further by explaining the interaction between dailyOvertimeHours and weeklyOvertimeHours (daily first, then weekly), the meaning of roundMinutes (5/6/15-minute shift rounding), and the default 1.5 multiplier. That interaction semantics is not obvious 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?

"Weekly time card: add shifts... Totals per shift, per day and per week" gives a specific verb (compute/add shifts) and resource (weekly time card with pay), which an agent can distinguish from neighbors like calc_salary or doc_attendance_sheet by inference. It stops short of naming an alternative explicitly, so it is clear rather than sibling-differentiating.

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 weekly-shift framing implies when the tool fits, but there is no explicit when-to-use or when-not guidance and no mention of alternatives (e.g. use calc_salary for a flat salary rather than shift-based hours). The agent must infer the selection condition from context.

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