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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description goes further with data provenance (late cancels live only on rosters, class totals omit them), the 47-hour roster cache, per-read credit costs, and Mindbody call volume. The one real gap is that these details are scattered across a dense paragraph rather than surfaced as discrete behaviors, making the credit/caching rules easy to miss on a fast read.

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?

The scoping and alternative-routing sentences are correctly front-loaded, but the block is a wall of text with no visual separation and repeated content: credit cost is stated three times (planned credits, 1 per roster read, 1 per class-list page) and skipEmptyClasses is explained twice. Condensing the cost model into one sentence would remove real redundancy without losing 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 an 8-parameter tool with no output schema, the description still tells the agent what comes back in each mode (classes to read plus credits and plan; nextStartDate plus what was counted) and warns about lower-bound results. Nothing needed to choose a mode, bound credit spend, or interpret results is missing.

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?

With 100% schema coverage the baseline is 3, and the description does add cross-parameter context the schema states only locally: maxClasses at most 300 per call, whole-day granularity for count, and nextStartDate as the continuation token. However, several statements (skipEmptyClasses lower-bound caveat, mode requirements) duplicate the schema text almost verbatim, so the marginal value is moderate rather than decisive.

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 and resource: "Counts late cancels in one site's past classes, by class type and by client, and no-shows where the studio records them." The breakdown dimensions (byClass / topClients) and the scope (one site, past classes) let an agent distinguish it immediately from class_attendance_summary or attendance_with_revenue.

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?

Names explicit alternatives with the condition that selects them: class_attendance_summary for attendance/fill rates, attendance_with_revenue for revenue per visit, sales_summary for sales. It also explains the estimate-vs-count decision and tells the agent to run estimate and count separately for a comparison period.

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