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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so "Read-only." adds nothing new. What the description does add is pagination flow and the downstream dependency of the returned uid; the default of 20 and max of 100 merely restate the schema. No mention of ordering, total counts, or result size behavior.

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?

Four short sentences, front-loaded with purpose and the required field, then paging, then follow-on use. Tight overall; the trailing "Read-only." is redundant with the annotations and slightly dilutes the payload.

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 10-parameter list tool with no output schema, the description leaves most filters unexplained and says nothing about the shape of returned bookings beyond nextCursor. An agent can call it, but cannot confidently use the date-range, team, event-type, or attendee filters without guessing.

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 only 20%, and the description only touches status (required), limit, and cursor. The other seven parameters (search, startDate, endDate, timezone, teamIds, eventTypeIds, attendeeEmail) are undocumented in both schema and description, so the agent must infer their filtering behavior.

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?

"List the user's bookings" gives a specific verb and resource, and the closing pointer (use a booking uid from this list to reschedule or cancel) implicitly separates it from cancel_booking and reschedule_booking. It does not explicitly name a sibling list tool to contrast with, so it stops short of a 5.

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?

It states that status is required, explains how to page (pass cursor from a previous nextCursor) and how the output feeds other tools. It gives no guidance on which status value to pick or when to narrow with the filter parameters, so usage context is clear but not exhaustive.

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