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

Goes well beyond the annotations: 'Omitted fields are left unchanged', 'Applies to future availability; existing appointments are kept and no one is notified', required scope locations:write (Admin role), and the return shape. These disclose mutation semantics, blast radius, and auth requirements that the destructiveHint/idempotentHint flags alone 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?

Dense but every clause earns its place: scope first, then field-level semantics, then alternatives, then side effects, then return value, then auth. Front-loaded and waste-free despite covering a lot of ground.

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?

Though there is no output schema, the description states the return shape ('full location setup, same shape as get_location_setup'), covers side effects, reversibility of existing appointments, and permissions. Nothing an agent needs to invoke this mutation safely 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 100%, so the schema already fully documents all six parameters including the slotsPerHour enum and door semantics. The description restates the field names parenthetically but adds no syntax or format detail beyond the schema, so the baseline of 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?

States a precise verb+resource ('Change only a location's scheduling rules') and enumerates the exact fields governed, immediately bounding scope. It explicitly names the sibling tools that own the fields it does NOT handle, so an agent can distinguish it from set_weekly_hours, update_location_details, and set_up_location without opening a 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?

Names three alternatives with the exact condition that selects each ('For hours use set_weekly_hours; for name, address, or timezone use update_location_details; to change settings together with hours... use set_up_location'). This is explicit when-to-use/when-not guidance with routing, exactly the top of the scale.

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