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

Annotations already cover the read-only/idempotent safety profile, and the description adds real behavioral context on top: holidays override the regular rotation, and the return includes an updated calendar, overnight counts, and new .ics/subscribe links. The one ambiguity is that 'Add ... Returns the updated calendar' reads like a mutation while readOnlyHint=true is declared, but this is defensible as a stateless transform rather than a clear contradiction.

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?

Three sentences, front-loaded with purpose, then behavior, then return shape — no filler. The holiday enumeration slightly overlaps the schema's built-in list but earns its place by helping an agent scope the tool.

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?

For a 2-parameter tool with no output schema, the description covers the prerequisite, the override semantics, and the return payload (calendar, overnight counts, .ics and subscribe links). That is close to everything an agent needs, with only the read-only-vs-mutating question left open.

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 50%, so the description must carry weight, and it does: it explains the alternate-by-year vs split-in-half behavior that maps to the `rule` enum and characterizes the holidays array as built-ins or spans (school breaks). It adds meaningful semantics beyond the schema, though schedule_url is left to the schema.

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 (add), a specific resource (holiday rotation) and names the producing sibling (make_custody_schedule), so an agent can tell this apart from make_custody_schedule and compare_custody_schedules immediately. It also enumerates the holiday categories it handles, which sharpens the scope further.

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 description establishes the prerequisite context that the calendar must come from make_custody_schedule, and explains the key condition of use (holidays override the regular rotation on those nights). It stops short of an explicit when-not or a direct alternative, so it is clear context without exclusions.

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