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

Annotations already flag this as a non-read-only, destructive, closed-world mutation, and the description adds meaningful context beyond that: an authorization requirement (owner sign-in) and partial-update semantics ("other days stay as they are"). What is not disclosed is that overwriting a day's existing hours replaces the prior value, which matters given destructiveHint=true, and nothing is said about the response.

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 tight sentences: authorization first, then what changes, then the value format and update semantics, then the alternative. Every clause carries information and nothing is padded.

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 7-parameter, purely optional-parameter mutation with no output schema, the description covers authorization, value format, sparse update behavior, and the sibling alternative. The remaining gap is confirming what a successful call returns or whether the full resulting schedule is echoed back, which an agent might want given no output schema exists.

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 0%, so the description must carry the burden, and it does: it explains the accepted value format (local "HH:MM-HH:MM" or "closed") and the critical sparse-update rule that only supplied days are changed. It stops short of clarifying per-day multiplicity (single interval only), timezone interpretation, or that omitted vs. empty days are equivalent to no change, all of which the pattern-constrained schema leaves ambiguous.

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 ("Change the pro's regular weekly hours") and adds a scope-defining fact that this is the only window set Latchbell offers. It also names the sibling it is not (block_time) for one-off exceptions, so an agent can distinguish it without reading either 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?

Explicit when-to-use (regular weekly schedule) plus an explicit when-not with the correct alternative ("For a one-off day off or a busy stretch, use block_time instead"). Prerequisites are stated up front: owners only and sign-in required.

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