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

The readOnlyHint=true annotation already establishes the safe read profile, lowering the burden. The description does add value by naming what the shift records expose (clock-in/out times, weekday, availability, recurrence), but it says nothing about pagination, result limits, or whether staff_ids narrows the result set.

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?

A single front-loaded sentence covers the verb, scope, and returned fields, followed by a terse GraphQL mapping hint. Nothing is padded or redundant.

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 read-only list tool with no output schema, full schema coverage, and safety annotations, the description conveys enough to call it correctly. The omissions (staff_ids filter behavior, pagination) are minor for a tool whose parameters are fully documented in the schema.

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 documents all four parameters including the location_id URN format and date patterns. The description only gestures at the date range and single location, adding no syntax or meaning beyond the schema; the staff_ids filter is entirely absent from the prose.

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 (List) and resource (staff working shifts) with the scope of one location and a date range, plus what the records contain. It is clear on its own, though it does not explicitly differentiate itself from the adjacent boulevard_list_staff or boulevard_list_timeblocks siblings, which an agent could plausibly confuse with shifts.

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?

The description implies the data domain (one location, date range) but never states when to use this tool versus alternatives such as boulevard_list_timeblocks or boulevard_list_staff, nor any exclusions or prerequisites. There is no explicit usage routing at all.

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