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

With no annotations, the description carries real behavioral weight and delivers: booking hours fall back to a default when unset, arrival_notices is off unless enabled, on_my_way_notices covers both the on-the-way and arrived notices, arrival times come from a stored route estimate or worker-entered time with no drive time lookup, and both notice types go by text and email. The only gap is it never states the read-only nature outright or the failure mode for an unknown shop_id.

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?

The resource and its fields are front-loaded well, but the prose is dense and partly redundant — after stating on_my_way_notices covers both notices, a later sentence repeats that on-the-way and arrived each go by text and email. The arrival-time parenthetical is crammed into a single line, hurting scanability.

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 single-parameter read tool with an output schema available and no annotations, the description supplies the behavioral context an agent needs: defaults, flag semantics, notice channels, and who can read it. Only the shop_id scoping and error behavior are unaddressed.

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% and the description makes no mention of shop_id at all — no scoping statement such as 'returns settings for the given shop'. The single parameter is self-explanatory by name and UUID format, which keeps this from being a 1, but the description adds nothing beyond the schema here.

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?

The description names the resource and enumerates exactly what the setting payload contains: time zone, booking hours (with default fallback), arrival window, travel buffer, reminder lead time, on_my_way_notices, and arrival_notices. That is specific enough to distinguish it from mutation siblings like schedule_setShopHours or schedule_setRules, though no sibling is named explicitly and no verb ('returns', 'reads') appears.

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?

Usage is only implied: the description frames the tool as reading the shop's scheduling setup and notes 'Any worker in the shop can read it', which signals a permission-safe read. It never says when to call this instead of schedule_list, schedule_events, or schedule_setShopHours, and gives no exclusions or prerequisites.

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