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

Goes well beyond the annotations: it discloses that the call is non-mutating despite readOnlyHint=false, that it returns a one-time intent plus the projected full week, that days becoming closed are included, and that company:write scope is required. These are exactly the behavioral facts an agent needs before wiring it into a two-step flow.

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 short sentences, front-loaded with the action, then the non-mutation guarantee, then the permission requirement. No filler and nothing repeated from the schema.

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?

Covers the essentials for a 3-required-parameter mutation with no output schema: what is staged, that nothing changes yet, what comes back, and the auth scope. Remaining gaps are the lifetime/expiry of the one-time intent and the day-of-week encoding, which an agent would have to guess.

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 0% schema description coverage the description must carry the load, and it partially does: location_id is constrained to the merchant's own locations, and "the full week as it would read" implies hours is a full replacement rather than a patch. However, idempotency_key is never mentioned and the dow/open/close encoding (which integer day-of-week convention, time format) is left entirely undocumented.

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 ("Stage new opening hours") plus a scope restriction ("for one of the merchant's own locations"). The phrase "Changes nothing on its own" immediately separates it from the sibling confirm_update_hours, so an agent can tell the two apart without opening 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?

Gives clear context for when to call it: this is the staging step, it produces a one-time intent, and it requires company:write. It never names confirm_update_hours as the follow-up call, so the agent must infer the next step from the sibling list rather than from the description.

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