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

Adds substantial behavior beyond the annotations: the change replaces that day's override, hours matching the weekly default clear the override, and 'nothing is sent to anyone' reassures the agent no notifications fire. It also discloses the return value (override ids plus booking conflicts left for a human to resolve) and the retry semantics of the idempotency_key, which refines the idempotentHint annotation with concrete behavior.

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?

Front-loaded with the core action, then the three modes, then side effects, then return value and retry rule. Every sentence carries distinct information with no filler, despite the dense packing of parenthetical field hints.

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 nine-parameter mutation with no output schema and near-zero schema descriptions, yet the description covers modes, range cap, overwrite/clear semantics, notification behavior, and return contents. It falls short only on the 'reason' parameter and on any authorization or permission expectations, which an agent might reasonably want for a staff-scheduling write.

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 only 11% schema description coverage, the description carries the load and mostly delivers: it defines the 92-day cap on end_date, the HH:MM shape for available_from/available_until, the windows structure for split shifts, and the meaning of day_off. It leaves 'reason' (a 500-char free-text field) and the exclusivity rules between modes unstated, and never says date is the range start.

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 ('Sets one field worker's availability for a date, or a date range') and enumerates the three distinct modes: day off, single shift, and split shifts. The mention that 'hours equal to the weekly default clear it' implicitly separates it from set_staff_weekly_hours and clear_staff_availability_override, so an agent can tell which tool it needs without opening the schema.

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?

Gives clear conditions and mode shapes: use day_off for a full day off, available_from + available_until for one shift, windows for split shifts, and end_date for ranges up to 92 days. It also tells the agent to reuse the idempotency_key on retries. The gap is that it never names an alternative tool or says when to prefer clear_staff_availability_override or set_staff_weekly_hours instead.

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