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

Annotations only declare readOnlyHint=true; the description adds substantive behavior: days are inclusive and interpreted in the company timezone, ranges are capped at 31 days, and laborPercentage is null (not 0%) when revenue is zero. The grossPay caveat for monthly-paid staff is a genuinely useful data-quality disclosure. It stops short of describing response shape or ordering.

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?

Short and front-loaded with the computed output, with no filler. However the telegraphic style with missing spaces and concatenated tokens ('at most31days', 'revenue0 is not0%') makes it harder to parse than an extra clause of plain prose would.

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, so the description carries the burden of explaining return values; it names laborCost, revenue, and laborPercentage but not the per-day array structure, date keying, or any other returned fields. Combined with the 31-day cap and timezone note, it is adequate to call correctly but incomplete about what comes back.

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 only 33% — departmentID is documented in the schema, but from/to are bare strings. The description partially compensates by establishing that from/to are inclusive day boundaries in the company timezone with a 31-day span limit, yet it never states the accepted string format (ISO date, epoch, etc.), leaving a real gap for the two undocumented params.

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 computed resource: per-day laborCost/revenue for a department, with a clear scope (from/to inclusive company-zone days, max 31). An agent can tell this is an aggregated stats tool rather than a raw record fetch. It does not, however, name the nearby siblings workfeed_get_department_day / workfeed_list_department_days to disambiguate.

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?

'Prefer laborCost here: shift grossPay is0 for monthly-paid staff' is guidance about which metric to trust, not when to call this tool versus the day/list siblings. There is no explicit when-to-use, when-not-to-use, or alternative routing, so usage must be inferred from the name.

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