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

Despite annotations already declaring mutation and idempotency, the description adds substantial behavioral context: partial-update semantics ('Only the keys you send in fields change'), null-as-reset behavior for both every and muted_until, what enabled:false does without forgetting the interval, and how changed_at resolves queued-edit conflicts with applied:false. This is exactly the kind of detail annotations cannot convey.

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 the core action and then the partial-update rule and usage trigger. Dense but nearly every clause carries operational meaning; the final read-back sentence is slightly tangential but still useful.

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 complex nested-parameter mutation with an output schema and annotations, the description covers when to use it, how partial updates behave, reset semantics, and where to read task state. Nothing an agent needs in order to call it correctly 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 description coverage is 80%, and the nested schema already documents the null-reset semantics for every and muted_until, enabled:false, and changed_at conflict handling. The description largely restates those same semantics rather than adding new meaning, so the baseline 3 applies.

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?

Names a specific verb and resource (set the user's own schedule for one maintenance task on one grinder/machine) and enumerates the three modes: own interval, switch off, or mute. It is clearly distinguished from siblings like log_maintenance and set_maintenance_offset, which handle logging and offsets rather than a full schedule.

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 an explicit trigger ('when the user states how often they do a task or asks to be left alone about one') and an explicit prohibition ('never to invent an interval'). It also points to list_grinders and list_machines for reading back state, but does not explicitly contrast with set_maintenance_offset, so it falls just short of naming alternatives.

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