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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not openWorld), so the description's job is added context, and it delivers: it discloses the return shape (per person, leave items with request_id and working-day counts, plus public holidays and on_leave people) and the default scope of today only. The 'Free' note also hints at cost. It does not discuss result size 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?

One dense but well-ordered sentence: scope and default first, then payload contents, then filters, then the include_pending switch. No filler and nothing repeated from the schema.

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?

A read-only reporting tool with no output schema, and the description explains what comes back, which is the key gap it needed to close. Minor omissions: no note on result size or limits, and no explicit relation to hr_list_leave.

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?

With schema coverage at 40%, the description compensates by explaining every parameter in prose: from/to with a today-only default, department and location as filters, and include_pending as including undecided requests. Date format is left to the schema, but the semantic role of each parameter is clear. The coverage gap is reasonably well covered.

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 report: who is off over a date range, with the exact payload (per-person leave, request_id, working days, public holidays, on_leave statuses). That is far more concrete than a generic 'list leave'. It stops short of naming a sibling such as hr_list_leave, so an agent must infer the distinction between 'absence overview' and 'leave records'.

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?

It gives useful scoping guidance ('default: today only', filter by department or location, include_pending for undecided requests), which is implicitly when-to-use context. However, it never says when to pick this over hr_list_leave or when not to use it, leaving the sibling choice to inference.

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