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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: exact upstream call costs (1 site lookup cached, 1 per 200 enrollments up to 2,000, up to 20 pages of missing sessions, up to 3 waitlist pages, capped at 34), the data-provenance caveat that Mindbody-omitted sessions come from the class schedule, and the scope limit "No student rosters." These are pricing and correctness facts an agent cannot get from the annotations.

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?

Purpose is front-loaded in the first sentence, followed by semantics, exclusions, and cost in a logical order with no filler. It is somewhat telegraphic in places ("No student rosters.", "Mindbody calls: ...") so it reads as dense rather than polished, but every sentence carries information.

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, multi-source tool with no output schema, the description covers scope, data provenance, cross-session attribution, and cost — enough to call it correctly. It stops short of enumerating the returned row fields (fill count, spots left, cancellation status) beyond passing references to courseWaitlist and withoutSessionData, leaving output shape partly inferred.

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 baseline is 3; the description earns a bump by clarifying semantics the schema does not, notably that waitlist figures split between session-level waitlists ("that session's teacher, location, and waitlist are its own") and courseWaitlist ("counts people waiting for the whole course"). It does not address individual parameters like sort or fullOnly, which remain fully schema-driven.

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?

"Which workshops, courses, or events are filling, full, or empty" states a specific resource and the exact measure (fill), and the closing sentence explicitly separates it from find_classes and class_attendance_summary. An agent can pick this tool over its siblings 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?

The description gives negative routing ("Not for single classes (find_classes) or class_attendance_summary") plus the positive scope condition that fill is computed from sessions inside the requested dates, "including a course already underway." Together these tell the agent both when this tool applies and which alternative to use otherwise.

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