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

Annotations declare a non-destructive, non-idempotent write; the description adds context annotations cannot express, such as the mandatory draft-first workflow, the default values applied when the user is silent (18:00 end, dark theme, month calendar view), and that a succeeded create never mutates an existing page. It stops short of stating collision/error behavior for a duplicate slug, which would matter for a create with a user-chosen address.

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 then immediately the routing rule, and nearly every sentence carries decision-relevant information. It is a dense single block of roughly 250 words, though, with the weekly_hours explanation mid-stream; the calendar/theme defaults could be tightened and sub-structure would aid scanning for a 14-parameter tool.

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 14-parameter create with high-stakes workflow dependencies, this covers the required workflow ordering, all format conventions an agent would otherwise get wrong, and the mutate-vs-create boundary. Return values are covered by the existing output schema, and workspace_id/conversation_id/idempotency_key conventions are covered by schema descriptions, so no critical gap remains.

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 coverage is only 29%, so the description must carry the load and largely does: it explains slug via the /c/<workspace>/<slug> link form with a worked example ('gods' from /c/zachary/gods), member_slug's scope restriction ('pass it only when the user asks to choose that, on their first page'), primary_color's hex requirement and name-to-hex conversion, weekly_hours' day-numbering, HH:MM format, entry-merging rule and break-splitting rule, plus theme and calendar_view defaults. title, location, description and duration_minutes get no explicit treatment, leaving a minor gap against a 14-parameter schema.

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?

Opens with a specific verb+resource ('Create a booking page') and immediately glosses it as 'the public link where people book a meeting with the user', which disambiguates it from siblings like well_create_schedule, well_create_calendar_event and well_update_booking_page. An agent can identify the target artifact without opening any 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?

Explicit routing rules: call well_get_booking_page_draft first when the host can draw cards, call this tool 'only when that result says card_drawn is false or when the user asks in chat to create it now', and an explicit negative rule that an existing page is changed via the draft tool and booking_page_id, 'never by a new create'. This is model when-to-use guidance including alternatives and exclusions.

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