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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that ("Read"). It adds non-obvious behavior beyond the annotations: the required key scope (bookings:write), the fact that the backing calendar resource cannot be created here and must be connected by a person in the admin, and that pages created elsewhere start paused as a draft.

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?

Front-loaded with purpose, which is good, but the body sprawls across the full page/resource CRUD lifecycle, an external product's URL, and an admin_url aside that belong to the sibling mutation tools rather than to a read-only status call. The enumeration of returned fields is informative but dense, and the piece reads as one long run-on.

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?

With only one parameter, no output schema and full schema coverage, the description compensates well by naming the returned fields, the auth scope, and the domain boundary. Remaining gaps are minor: no note on result size/pagination and no contrast with get_booking_page/get_booking_resource.

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?

One parameter (site) at 100% schema description coverage, so the schema already explains it is the id from list_sites. The description adds no site-scoping nuance (e.g. multi-site behavior or what happens with an invalid/unauthorized site id), so the baseline 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 specific verb and resource ("Read the site's booking setup") and enumerates what is returned: resources with status/paused_reason/timezone/version and booking pages with title/form_key/duration_min/hours/public_url. What it does not do is distinguish itself from the read siblings get_booking_page and get_booking_resource, which return overlapping data for a single page/resource, so an agent must infer the overview-vs-detail split.

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?

Strong exclusion guidance: it explicitly says memberships, coupon books, class booking and capacity-limited slots are out of scope and should be redirected to Gym rather than built. It also routes the mutation lifecycle to booking_page_create/update/publish/remove. The gap is that the closest read alternatives (get_booking_page, get_booking_resource) are never named, so the most likely misuse case is unaddressed.

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