StudioVector: Chat with your Mindbody

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered structurally. The description usefully adds what data surfaces (credit balances, reset period, seats, site locations), which is real value beyond the annotations. It does not say whether the data is live or cached, nor what happens when no account is connected — gaps that matter for an account-context call.

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?

A single sentence that front-loads the resource and then lists the payload in a compact, scannable order (plan → limits → credits → seats → sites). Nothing is redundant, though the comma chain of noun phrases is dense and slightly harder to parse than a short bulleted framing would be.

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 no input parameters and no output schema, the description carries the burden of conveying return content, and it does so by naming each category of data. For a simple read-only overview this is close to sufficient; the main omission is any indication of freshness or behavior when the account is not yet connected.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The brief enumeration of returned fields is the only substantive content, and it does not describe structure or units.

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?

The description names the specific resource (the user's StudioVector account) and enumerates its contents: plan and status, limits, credits used/remaining with reset timing, seats, and connected sites' locations. That is far more informative than the title alone and lets an agent distinguish it from analytical siblings like studio_kpis or membership_summary. It stops short of a verb-led framing (e.g., 'Retrieve...'), but the resource scope is unambiguous.

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?

Usage is implied rather than stated: an agent can infer this is the entry point for account-level context before drilling into studio_kpis, get_sites, or studio_connection_status. There is no explicit when-to-use or when-not-to-use guidance, and no mention that connection state overlaps with studio_connection_status, so the agent must infer the boundary.

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

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

Annotations only say read-only/idempotent/non-destructive; the description adds substantive behavior: windows whose last start has passed on the studio's clock are excluded, results are capped at 8 bookable pages of at most 10, site and session-type lookups are cached, and omitted sessionTypeIds fall back to the first 8 online-bookable types. These are operational facts an agent cannot derive from the annotations or schema.

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 and the definitional sentence about windows is well placed before the output-field explanation. It is dense but nearly every sentence adds information; the closing Mindbody-call/pagination sentence is the most implementation-heavy and could be trimmed slightly.

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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so field by field (window count, first start, lastStart, start minutes, estimatedSlots). Combined with exclusion rules, caps, and defaults, an agent has everything needed to call it correctly and interpret results.

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 100%, so the baseline is 3, but the description adds meaning the schema lacks: it explains that results are grouped by session type and staff (which determines what 'limit' counts), defines lastStart and estimatedSlots, and warns that wide queries need sessionTypeIds or staffIds. The date-range and staff/location caps themselves remain schema-only.

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?

The opening clause states a specific verb and resource: 'Where a client can still be booked: open availability windows grouped by session type and staff.' It then defines what a window is ('a stretch of free time, not one slot'), which prevents the common misreading of the result as individual bookable slots and separates it from booking-lookup siblings like get_staff_appointments.

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 gives a clear use condition (finding bookable availability) plus explicit exclusions: it does not report historical appointment statuses, no-shows, or booked hours, which steers agents elsewhere for those needs. It also states a query-scope rule ('must pass session types or staff rather than expecting an unbounded scan'). It stops short of naming the specific sibling to use for historical or booked data.

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

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

Beyond the annotations, the description discloses substantial behavior: unknown revenue is counted but never guessed, comp is unavailable, empty classes unchanged since 48 hours before start are skipped, pages read in the last 47 hours are reused at no cost, and exact credit and Mindbody call limits are given. This is unusually transparent for a read-only reporting tool.

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 purpose is front-loaded, but the description is a dense single block that packs modes, formulas, caching rules, exceptions, and call limits together. Most content is useful for a complex 19-parameter report, yet the lack of paragraph or bullet structure makes it harder to scan than it should be.

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 complex 19-parameter reporting tool with no output schema, the description covers the important behavior: mode selection, revenue calculation, pricing basis, unlimited options, skipped empty classes, continuation via nextStartDate, caching, and credit limits. It stops short of fully describing the returned section and row shapes, but it is otherwise close to complete.

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 100%, so the schema already defines the parameters. The description still adds meaningful semantics beyond the schema, especially for priceBasis paid/list/none, unlimited include/exclude treatment, mode behavior, and how maxClasses affects estimate versus count. It does not explain every one of the 19 parameters in prose, but it adds enough pricing and mode context to exceed the baseline.

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?

The description states a specific verb and resource: Mindbody's Attendance with Revenue report for one site's past classes and appointments, with revenue by service category, staff, pricing option, and other views. It clearly distinguishes the revenue report from a plain attendance variant, but it does not explicitly position itself against sibling tools such as class_attendance_summary or get_class_visits.

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 gives clear internal mode guidance: estimate reads only the class list and returns a plan and credits, count requires maxClasses and reads rosters, and totals is for counts only without revenue or rosters. It also advises asking for every needed section in one call. The main gap is that it does not say when to choose this tool over sibling attendance tools.

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

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

Beyond readOnly/idempotent annotations, it discloses non-obvious rules: canceled classes are counted separately and excluded from all rates, fill rate is booked/capacity over classes with capacity, sign-in fields appear only for ended classes at studios that record sign-ins, and Mindbody call cost is 1 per 200 classes (doubled with compareToPrevious, max 50).

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 the question it answers and the outputs, then definitions, then routing and cost. It is one dense run-on paragraph with some redundancy (filters repeated as 'location, teacher, program or class type IDs'), but nearly every clause carries substance.

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 11-parameter, no-output-schema aggregate tool, the description supplies the return contents, rate definitions, edge cases (no capacity, canceled classes, sign-in availability) and cost model. An agent has enough to call it correctly and interpret results without an output schema.

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 100%, so the schema already documents every parameter including range, include, top and compareToPrevious semantics. The description only restates filter dimensions and the 92-day / comparison behaviors that the schema already spells out, adding little marginal meaning.

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 framing ('Answers class attendance questions in one call') and enumerates the exact metrics returned (fill rate, booked, waitlisted, signed in). It explicitly positions itself against find_classes and class_mix, so an agent can distinguish it from siblings without inspecting schemas.

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?

Gives explicit routing: 'Use this instead of find_classes for attendance and fill-rate questions' and points to class_mix for the not-signed-in rate over only sign-in-recording programs. It also states the date-range and call-budget constraints that govern when the tool is practical.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the computation source (totals already stored on each class, not a per-class roster), the in-progress vs upcoming split, local-time handling via a cached site lookup, and the API cost model (1 site lookup cached, then 1 call per 200 classes, max 11). Cost and timezone behavior are exactly the traits annotations cannot carry.

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 first sentence is long and clause-stacked, but no sentence is filler — scope, exclusions, sibling routing, and cost each appear once. Slightly tighter sentence splitting would improve front-loading of the core 'what you get' claim.

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 no output schema, the description still names the key returned values (notSignedInPct, upcomingBooked), the population it aggregates over, and the exclusions. For a read-only reporting tool of this complexity, an agent has everything needed to call it correctly and interpret the result.

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% and the schema already documents range, dates, the 31-day cap, and the 'do not pass range as well' rule, so the description clears the baseline. It adds only indirect meaning (the studio's clock governs what counts as started), with no extra detail on date formats or site selection beyond the 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?

The description names a specific output (class names and programs attended, plus notSignedInPct) and is explicit about the resource being class bookings/sign-in totals rather than rosters. It also states the boundary 'Classes only: appointments and enrollments are not counted,' which lets an agent separate it from appointment and enrollment siblings without opening a 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?

It explicitly routes to alternatives: 'class_attendance_summary is fill and busiest times' and 'find_likely_attendees is who to expect,' plus a clear exclusion of appointments and enrollments. Combined with the 'already started on the studio's clock / upcomingBooked' distinction, an agent knows both when to pick this tool and how its range is interpreted.

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

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

Beyond the readOnly/idempotent annotations it discloses upstream call costs (1-2 calls for profiles/memberships across all clients, 1 per client for services/contracts and for visits/schedule, capped around 30), that contracts are slow because Mindbody returns full contract text, and that a failed section surfaces under "errors" without losing the rest. This partial-failure and cost disclosure is exactly the kind of context annotations cannot carry.

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 what is returned, then cost, then alternatives – a sensible order with no filler sentences. It is dense in a single block, and the Mindbody call-count details are heavy, but every sentence carries actionable 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 5-parameter aggregate read with no output schema, the description covers the returned sections, the optional heavy section, the caller's control over scope, and partial-failure behavior. An agent can call it correctly and interpret results without further documentation.

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 schema already explains siteId, include, clientIds, visitsLimit and scheduleDays including defaults and ranges. The description only reinforces the default section set and echoes the slow-contracts caveat that the schema already states, so it adds little new meaning.

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?

Names a specific resource (one or more clients, up to 10) and enumerates exactly what is returned: profile and balance, memberships, pricing options with sessions remaining, visits, bookings, and optionally contracts/autopay. It clearly separates itself from find_client and clients_at_risk, which are for locating clients rather than reading them.

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?

Explicitly says to prefer this over reading visits, memberships, contracts or bookings one client and one endpoint at a time, and routes discovery workflows to find_client or clients_at_risk. It also gives a positive usage rule: ask only for the sections you need.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description goes further by quantifying Mindbody call costs per 200 profiles and the 110-call ceiling, plus noting that sampling and truncation happen. It also discloses a return-side behavior: a 'coverage' field saying what was read and omitted, and clients sorted by earliest date.

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?

Sentences are front-loaded and dense with useful detail, but the long run-on enumeration of reasons and the nested call-cost listing make it hard to scan, and there is a duplicated word typo ('within withinDays').

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, no-output-schema tool, the description covers sorting, truncation, the coverage/summary fields, and cost ceilings — everything an agent needs before spending up to 110 Mindbody calls.

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 100%, so the baseline is 3, but the description adds real meaning: it explains how withinDays, lowSessions and inactiveDays interact (packs with more sessions left but expiring within the window) and frames maxRenewalChecks/maxVisitChecks as per-call cost drivers with least-recently-updated sampling.

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?

The description opens with a specific verb and resource ('Lists clients at one site who may not renew') and enumerates the exact risk reasons (autopay expiry, Mindbody statuses, low/expiring packs, visit decline). This clearly distinguishes it from the single-client sibling, which is named explicitly.

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 names the alternative ('Use client_overview for one client's details') and gives a concrete cost-based configuration ('signals ["renewals"] with maxRenewalChecks 0 is the cheapest call: statuses only'). It also states a precondition for downstream marketing actions (check SendPromotionalEmails/Texts).

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), and the description adds the genuinely non-obvious part: this is a two-phase flow requiring the business owner to approve in Mindbody, with divergent outcomes (activation link/code, sent for review, or already owned by another account). It does not discuss what happens on repeated calls or the live-ness/lifetime of the returned code, but the external-approval behavior is disclosed well.

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?

Three compact sentences ordered as purpose, eligibility, outcomes, then next step. The routing to the sibling tool is front-loaded at the end rather than buried, and no sentence is redundant with structured fields.

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?

There is no output schema, so the description carries the return-value burden and does so by enumerating the three possible outcomes and the next call. For a single-parameter mutation with annotations covering safety, nothing an agent needs before invoking 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?

Schema description coverage is 100%: the single siteId parameter has its own description, example, and pattern. The tool description adds no further meaning about the parameter (e.g., where to obtain the Site ID), so the baseline of 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 ('Starts connecting a Mindbody business (site) to the user's StudioVector account') and explicitly distinguishes itself from the sibling studio_connection_status, which it names as the follow-up step. An agent can tell what this initiates without opening the 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?

Gives an explicit audience precondition ('For owners and admins of an account with an active plan') and a clear sequencing rule ('Then call studio_connection_status'). It does not address what to do if the caller is not an owner/admin or if a connection already exists, which keeps it short of a full when/when-not treatment.

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

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.

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, so the burden is lighter. The description still adds genuinely useful behavior beyond them: the 31-day maximum window, sorted output, paging handled internally, and an explicit cost model of one Mindbody call per 200 classes capped at five. It does not explain failure modes or whether results can be truncated at the call cap.

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?

Three tightly packed sentences that lead with what is returned, then filtering, then limits and cost, then when to use it. The middle sentence enumerating filters is somewhat redundant with the schema, but nothing is padded or buried. Front-loading is good.

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 12 optional parameters, no output schema, and no required arguments, the description carries the return-shape burden and does so by listing the row fields. It also discloses the date-window cap, cost ceiling, and sorting behavior. The only gap is that it does not say what happens when the five-call cap is hit or whether results are truncated.

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 schema already documents every parameter including defaults, enums, and lookup hints (get_programs, get_class_descriptions). The description mostly restates the filter set and the 31-day bound rather than adding new semantics. 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?

The description opens with a specific resource and scope: classes within a date range returned as compact rows, and it names the actual row fields (time, name, staff, location, capacity, spots left). It is clearly a schedule-browsing/search tool rather than an attendance or revenue report. It stops short of naming which sibling tool to pick instead, so it is clear but not fully differentiated.

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 closing sentence gives a concrete usage context: browsing the schedule or looking for open spots. That is enough to steer an agent away from attendance/summary siblings. There is no explicit when-not guidance or named alternative tool, so it misses the top band.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, openWorld), the description discloses response shape ('compact rows (id, name, contact, status)'), result ordering ('best matches first'), a duplicate-flagging behavior, and API cost ('Mindbody calls: 1 (at most 1)'). These are non-obvious traits an agent could not infer from the structured fields.

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 what the tool does and what it returns, followed by sibling routing. No filler and no repetition of annotation content.

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?

There is no output schema, so the description must carry the return contract — and it does, listing the returned columns, sort order and duplicate flagging. Combined with the schema-documented parameters and the safety annotations, nothing needed to call the tool correctly 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?

Schema description coverage is 100%, so query, limit, siteId and includeInactive are already fully documented in the schema. The description restates the query modes (name/email/phone) but adds no format or precedence detail beyond what the schema provides; the 3 baseline applies when the schema carries this burden.

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?

The description opens with a specific verb and resource ('Find clients by name, email or phone') and immediately distinguishes the tool's scope from siblings by naming client_overview for detail lookups and clients_at_risk for a different search intent. An agent can select this tool without opening the 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?

It gives explicit routing: use the returned id with client_overview for one client's details, and use clients_at_risk when looking for clients who may not renew rather than a known client. Both alternatives and the condition that selects them are stated outright.

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

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

Goes well beyond the supplied annotations by disclosing the scoring rubric (0-100 on frequency, recency, kept bookings, plus weekday/time/instructor matching for a classId), the ordering of history read, and the exclusion of already-booked clients. It also documents cost and limits (1 call per 200 past classes, up to maxClasses, at most 112 calls) and the auth requirement (staff token that may view class rosters) with the fallback behavior when rosters are unavailable. That is exactly the context annotations cannot carry.

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-loads the purpose, then input modes, then ranking behavior, then cost, then auth constraint – a logical progression. It is a dense block of prose with no line breaks, and the call-cost sentence is long, but no sentence is filler.

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 no output schema, the description still covers what is returned (top clients with contact details and active memberships), the ordering, the exclusion rule, and the degraded-but-informative response when rosters are inaccessible. For an 8-parameter read tool that fans out into many upstream calls, this is complete.

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 100%, so baseline is 3, but the description adds real meaning: it ties classId to find_classes, explains that className matches any class type containing the substring, and clarifies that maxClasses drives per-class call cost. The interplay between match mode and ranking inputs (weekday/time/instructor apply only for classId) is a genuine semantic addition.

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 ('Finds the clients most likely to book a class') plus the intended outcome ('fill open spots or target a promotion'), which distinguishes it from lookup siblings like find_classes and find_client. An agent can tell this is a ranked-prospect tool, not a roster or a profile lookup.

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?

Gives explicit selection guidance between the two input modes (classId from find_classes vs className like "yoga") and states an exclusion rule (already-booked clients are dropped). It does not name competing siblings such as clients_at_risk or enrollment_fill, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds a modest operational signal ("Mindbody calls: 1") that hints at API cost, but says nothing about pagination behavior, the includeInactive default of true, or what the filtered/unfiltered result sets look like.

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 text is short, but the opening line is boilerplate that duplicates the title and exposes a raw endpoint path, and the capitalized parameter names don't match the schema's camelCase. The one substantive sentence does arrive quickly, so it isn't padded, just partly wasted.

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 read-only, ten-parameter listing tool with full schema coverage and clear annotations, the essentials are present and the scheduled-class filter note is genuinely useful. However, it never explains the resource itself or how it relates to the many sibling class/reporting tools, leaving an agent to guess at the boundary.

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 schema already documents all ten parameters well, including date formats and the includeInactive default — that establishes a baseline of 3. The description only re-lists four filter parameters (with inconsistent capitalization: StaffId vs. staffId) and adds no meaning beyond what the schema states more precisely.

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?

The description states a verb and resource ("Get Class Descriptions") plus the underlying HTTP path, but the first clause is essentially a restatement of the tool name and title, adding no explanation of what a "class description" actually is. The second sentence pivots to filtering behavior rather than clarifying purpose, and there is no differentiation from siblings like find_classes, get_class_visits, or get_session_types.

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 gives one concrete usage condition: pass staffId, startClassDateTime, endClassDateTime, or locationId to get descriptions tied to scheduled classes. That is a real when-to-use hint, but it only covers one scenario — there is no guidance on when to call this instead of find_classes or get_session_types, and no mention of the unfiltered case returning all descriptions.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds real behavioral detail beyond them: response shape (class object plus list of visits) and the edge case that an invalid LastModifiedDate silently defaults to null rather than erroring. That null-default behavior is exactly the kind of trap an agent needs to know about.

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 alternates between a restated title/endpoint, a stray "Mindbody calls: 1" fragment, the alternative-tool routing, the return description, and a date caveat, with no clear ordering logic. No sentence is harmful, but the header echo and the orphaned call-count note are filler that push the useful routing advice into second position.

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 no output schema, the description carries the return-value burden and does so (class object with a list of visits). Combined with full schema coverage and annotations covering the safety profile, an agent has enough to invoke it correctly; only pagination or roster size expectations are unaddressed.

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 100%, so the baseline is 3, but the description earns above baseline by documenting failure-mode semantics the schema omits: an invalid date passed via LastModifiedDate defaults to null instead of raising. It does not clarify classID sourcing or the siteId default, but those are already fully specified in the 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?

The description states a specific verb+resource ("get class visits" / "Returns a list of visits that contain information for a specified class") and explicitly names a sibling it is not (find_likely_attendees). The leading name-plus-endpoint echo ("Get Class Visits — GET /class/classvisits") adds no information beyond the title, but the substantive sentence makes the purpose unambiguous.

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 gives one explicit routing rule with the selecting condition: if the goal is finding clients likely to book a class, use find_likely_attendees instead, because that tool reads and ranks many rosters in one call. It does not address other closely-related siblings such as class_attendance_summary or attendance_with_revenue, so the when-not coverage is partial rather than complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that results vary by site configuration and location, which is useful context, but says nothing about result set size, pagination behavior, or permission requirements.

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-loads the endpoint path and the call-count metadata, which is useful operational context. The second sentence is somewhat repetitive of the first ('available on a location-by-location basis' vs 'depending on the configurations established by the site') but nothing is seriously wasted.

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 no output schema, the description carries some burden for describing return values, and it only vaguely characterizes the payload as contracts and autopay options. For an eight-parameter read tool it is adequate, but an agent would not know the response structure or whether pagination metadata is returned.

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 schema already documents all eight parameters including soldOnline, contractIds, and promoCode. The description contributes no additional meaning about parameter interactions or defaults, which is acceptable given full schema coverage but adds no value.

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 ('Get Contracts — GET /sale/contracts') and explains that it returns contracts and autopay options on a location-by-location basis. The purpose is unambiguous, but it does not distinguish itself from adjacent catalog tools such as get_memberships, get_products, or get_services.

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?

Usage is only implied: the description notes the options are used to sign up clients for recurring payments, which hints at the enrollment use case. It gives no explicit when-to-use/when-not-to-use guidance and never names the sibling tool an agent should pick instead for memberships, services, or pricing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds materially new behavior: cost ('Mindbody calls: 1'), a data-visibility caveat that an absent or under-permissioned user token returns only a reduced staff field set (FirstName, LastName, Id, Bio, DisplayName, ImageUrl), and a real pitfall that enrollment.Id should be joined to occurrence.ClassScheduleId because the enrollment's own ClassScheduleId is often empty. That is exactly the kind of context annotations cannot carry.

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-loads the endpoint and the sibling routing before the explanatory prose, which is the right order for an agent skimming. The definition paragraph is somewhat verbose borrowed API-doc copy, but each remaining sentence (call cost, token permissions, join key) carries operational value.

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, zero-required, read-only list tool with no output schema, the description supplies the things most likely to trip an agent: date defaults, the reduced-field response under weak auth, and how to join enrollments to schedule occurrences. It stops short of describing pagination behavior or the response envelope, though the annotation set covers safety.

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 all ten parameters (date range, staffIds, programIds, locationIds, sessionTypeIds, classScheduleIds, paging, siteId) are already self-documenting. The description adds no input-level meaning such as date-format quirks or interaction between startDate/endDate defaults; the join-key note concerns interpreting results rather than supplying parameters.

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+resource ('Get Enrollments' / GET /enrollment/enrollments) and then defines what an enrollment actually is (a service offered to multiple students who commit to all/most sessions), which is essential domain grounding. It also explicitly distinguishes itself from the sibling enrollment_fill, so an agent can separate the two without opening the 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?

Gives explicit routing: use enrollment_fill for which workshops are filling/full/empty. It also describes default scoping (no dates given -> today's date; no IDs given -> all return) implicitly through the schema. It does not address other nearby siblings (find_classes, get_class_visits) or say when this tool is not appropriate, so it falls short of a full when/when-not map.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the endpoint and a cost signal ("Mindbody calls: 1"), which is genuinely useful beyond annotations, but says nothing about pagination behavior or whether the result set is bounded.

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?

It is short and front-loaded, but wastes a line repeating the title and uses a terse, unexplained phrase ("Mindbody calls: 1") that an agent must interpret. Nearly every sentence duplicates structured fields rather than adding 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 simple, fully annotated, no-required-parameter read tool with complete schema coverage and no output schema, the essential facts (what it returns, that it is scoped to a site) are present. The missing gap is the relationship to get_sites, which is a routing rather than a calling-correctness issue.

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%, with limit, offset and siteId each documented in the schema, so the description carries no burden here. It adds no meaning about siteId scoping or page-size semantics beyond what the schema already states, which lands at the baseline.

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?

The description states the verb and resource ("Get locations for a site") and names the underlying endpoint, which makes the basic operation identifiable. However, it never distinguishes this from the sibling get_sites, a closely related concept, and it restates the tool name twice instead of using that space to sharpen purpose.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named. Sibling get_sites exists and is not mentioned, so an agent has no rule for choosing between them.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds a cost/rate disclosure ('Mindbody calls: 1') that an agent can use for budgeting, but says nothing about pagination, result volume, or default truncation 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?

It is short and front-loaded, but the final sentence 'Get the memberships at a site' largely restates the tool name and the route line, so one of three lines is redundant. The routing tip is well placed, yet the body is fragmentary rather than structured.

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 simple two-optional-parameter read tool with full schema coverage and rich annotations, most of what an agent needs is present. With no output schema, however, the description never hints at what a membership record contains or how results are shaped, leaving a gap it could have filled.

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% and both parameters are fully documented in the schema, including the 'all IDs allowed by access level' default, so the description carries no parameter burden. It adds nothing beyond the schema ('at a site' merely echoes siteId), which is the baseline case.

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 ('Get the memberships') and even the underlying route (GET /site/memberships), and explicitly distinguishes itself from membership_summary. The only weakness is that the scope 'at a site' is bare-bones, but an agent can still tell this apart from its siblings.

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?

Provides a clear routing rule to the sibling membership_summary for the count-of-clients-per-membership question, which is genuine when-to-use-elsewhere guidance. It does not spell out when-not to use this tool or any prerequisites, so it falls short of a full 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description's only added behavioral detail is 'Mindbody calls: 1' and the underlying endpoint, which is mildly useful for cost awareness but says nothing about result ordering, pagination limits, or default filtering (e.g., that sellOnline defaults to false and returns all products).

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 body is a single efficient sentence, but the front-loaded boilerplate ('Get Products — GET /sale/products', 'Mindbody calls: 1.') restates the title and exposes transport trivia before the actual meaning. Trimming that would make the sentence fully front-loaded.

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 filter tool with no output schema, the definition should hint at what a product record contains (id, name, price, barcode) since no structured field describes the response. Annotations cover the read-only/idempotent profile and the schema covers inputs, so the gap is moderate rather than severe.

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 description coverage across all 10 parameters, the schema already explains every field, including the locationId tax default and the sellOnline behavior, so baseline 3 applies. The description adds no additional parameter semantics such as how searchText interacts with productIds or category filters.

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 ('Get retail products') plus a scope qualifier ('available for purchase at a site'), which is more informative than a restated title. It does not, however, distinguish itself from the closely named sibling get_products_inventory, leaving an agent to guess which one returns sellable catalog items vs. stock levels.

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?

There is no when-to-use guidance, no exclusions, and no mention of the obvious alternative (get_products_inventory) despite it being in the sibling list. The phrase 'available for purchase at a site' implies a retail-catalog context but never states when to prefer this tool over the inventory or sales tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the pagination ceilings ('at most 50 per call, offset up to 100') and a 'Mindbody calls: 1' quota signal, but says nothing about result ordering, what an empty inventory means, or how site scoping affects results.

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 description is short and mostly front-loaded with the endpoint and purpose. The leading name restatement and the disconnected 'Mindbody calls' fragment make it slightly less clean, but nothing is padded or redundant at length.

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 six all-optional parameters, full schema coverage, read-only annotations, and no output schema, the essentials are covered. The key gap is sibling differentiation — nothing explains how per-site inventory differs from get_products, which matters in a 34-tool server where names overlap.

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 all six parameters are already documented, including the filter semantics ('response only contains details about the specified Ids'). The description's pagination statement duplicates the limit/offset schema text rather than adding new meaning, 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?

The description names a specific verb and resource ('Get retail products inventory data available at a site') and includes the underlying endpoint, so an agent knows it returns per-site retail inventory. It does not, however, distinguish this from sibling tools like get_products or inventory_to_reorder, which an agent would need to disambiguate a catalog read from an inventory read.

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?

There is no explicit guidance on when to use this tool versus get_products or inventory_to_reorder, nor any prerequisites mentioned. The only conditional hint is implicit in the schema filters (barcodeIds, productIds, locationIds), which the description never surfaces as a usage rule.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds the underlying API call count ('Mindbody calls: 1'), which is useful cost information, but says nothing about result volume, pagination defaults, or how filtering interacts with the returned set.

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?

It is short and front-loaded, but the first line merely repeats the title and name plus a raw HTTP path, and the disjointed 'Mindbody calls: 1' fragment reads as internal telemetry rather than guidance. Minimal waste in length, but low information density.

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 simple read-only list endpoint with a fully documented six-parameter schema and complete annotations, the description covers the essentials, and no output schema means return values need not be explained. The main gap is the conceptual overlap with get_services and get_session_types, which leaves an agent without disambiguation.

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 all six parameters (limit, offset, siteId, onlineOnly, programIds, scheduleType) are fully documented in the schema, which sets the baseline at 3. The description mentions no filters at all and therefore contributes nothing beyond the structured 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?

It gives an endpoint (GET /site/programs) and a purpose sentence, but that sentence says 'service categories offered at a site,' which conflicts with the tool name and blurs the line with siblings get_services and get_session_types. An agent cannot confidently tell whether 'programs' here means service categories or something else.

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?

There is no when-to-use guidance, no exclusions, and no routing to alternatives such as get_services, get_session_types, or find_classes, despite several siblings covering nearby concepts. The reader must infer usage entirely from the name and endpoint.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real operational context beyond them: one Mindbody API call per invocation and hard pagination ceilings (50 per call, offset up to 100). The note that there is no location filter because each sale carries LocationId is genuinely useful scoping behavior. It does not describe the shape of a returned sale record, which is the main remaining gap given there is no output schema.

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 purposeful content is front-loaded, but the block mixes URL, call-count, alternative routing, pagination, and a location caveat without clear separation, and repeats the sales_summary recommendation. The final sentence restating the resource feels tacked on rather than additive.

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 7-parameter, all-optional listing tool with full schema coverage, the description covers routing and pagination limits adequately. It leaves open what a sale record contains and how the tool behaves when no date range is supplied, both of which matter for a record-listing endpoint with no output schema.

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 limit/offset/date/payment filters are already fully documented and the description's restatement of them adds little. The one piece of value beyond the schema is the clarification that siteId functions as a header and does not filter results by location. Baseline 3 is appropriate.

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 concrete verb+resource ("Get Sales — GET /sale/sales") and clarifies the unit returned: individual sale records completed at a site, at most 50 per call. It explicitly disambiguates from sales_summary and studio_kpis, so an agent can route without opening schemas. The trailing sentence "Get sales completed at a site" is a bit redundant with the header but does add scope.

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 alternatives with conditions: sales_summary for revenue totals/breakdowns, studio_kpis for a period scorecard, and this tool for record-level lookup. The guidance is clear but repetitive — sales_summary is recommended twice in near-identical phrasing ("totals and breakdowns" then "a sales breakdown"), which adds noise rather than new routing information.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile needs no restating. The description adds useful operational context in 'Mindbody calls: 1' (cost per invocation) and the note distinguishing MembershipId values from client contract IDs, but it says nothing about pagination behavior or response shape. The caveat also references 'RestrictToMembershipIds', a parameter that does not appear in this tool's schema, which weakens the added value.

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 definition is short and front-loads the endpoint and purpose, which is good. However, the 'Get Services — GET /sale/services' opener largely restates the name and title, and the RestrictToMembershipIds note consumes a full line to describe a parameter this tool does not accept.

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 read-only, 14-optional-parameter list tool with full schema coverage and no output schema, the description covers purpose and invocation cost adequately. The main residual gap is that an agent gets no sense of what distinguishes a 'pricing option' result from products or contracts, which matters given the crowded sibling set.

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% across 14 parameters, so the schema does the heavy lifting and a 3 is the correct baseline. The description's only semantic addition is the MembershipId-versus-contract-ID note, which does not map to any parameter present in the schema, so it contributes little for this specific tool.

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?

The description pairs a specific verb and resource with the underlying endpoint (GET /sale/services) and clarifies that 'services' means 'pricing options available for purchase at a site', which is the key disambiguation an agent needs. It never names a sibling such as get_products or get_contracts, so the boundary between services, products, and contracts is left to inference.

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?

There is no explicit when-to-use guidance and no comparison against adjacent tools like get_products, get_contracts, or get_session_types, even though 'service' overlaps heavily with those concepts. The only guidance-like content is an ID-type caveat that does not name an alternative tool or a selection condition.

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

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

The annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds a useful cost signal ('Mindbody calls: 1') and the backing endpoint, but says nothing about pagination behavior, default result volume, or how limiting interacts with the site scope.

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?

It is short and front-loaded, but the first clause merely restates the tool title verbatim before adding the endpoint, and the 'Mindbody calls: 1' fragment is presented without explanation. Little is wasted, yet little is gained per sentence.

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 read-only, single-call listing tool with annotated safety hints, full schema coverage, and no output schema, the description is minimally sufficient. It never explains what a session type record contains or how results are ordered, leaving the agent dependent on the schema alone.

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 100%, with limit, offset, siteId, onlineOnly and programIDs all documented including defaults and filter semantics, so the baseline is 3. The description contributes no additional parameter meaning beyond what the schema already provides.

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 ('Get the session types used at a site') and even names the underlying endpoint GET /site/sessiontypes, so the agent knows exactly what is retrieved. It does not distinguish itself from near-siblings like get_programs or get_services, so it falls 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?

There is no when-to-use guidance, no exclusions, and no reference to any alternative tool. The agent must infer from the name alone that this is the lookup for session types, with no cue about when get_programs or get_services would be preferable.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered, but the description adds non-obvious behavior the schema cannot express: multi-site or unfiltered queries return deliberately limited per-site data, and full configuration requires a separate single-SiteId call. That payload-shape pitfall is exactly the kind of behavioral context an agent needs to avoid a wrong conclusion from the response.

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 front-loaded purpose and the two bullet rules are efficient, but the important-behavior section repeats the same point three times ("expected behavior", "reduce payload size", "we recommend retrieving the list of site IDs first"), and the Mindbody call count plus endpoint path add little for an agent. Roughly a third of the text is restatement.

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 read-only, six-parameter, non-nested tool with no output schema, the description covers the dominant risk (partial data on multi-site queries) and the calling pattern thoroughly. Minor gaps remain around pagination defaults and the two include* flags, which the schema does label but the description never contextualizes.

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, and the description goes beyond it by explaining the semantic difference between the siteIds array being omitted, containing one element, or containing many. It does not explain includeLeadChannels, includePerStaffPricing, the siteId header default of -99, or limit/offset paging, so it stops short of full coverage.

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 ("Gets a list of sites") plus the access scope ("sites that the developer has permission to view"), and names the concrete endpoint GET /site/sites. An agent can distinguish this from siblings like get_locations or connect_studio 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?

Gives explicit branching rules: no SiteIds returns all accessible sites, one SiteIds returns detailed info for that site, and it recommends retrieving the ID list first then querying each site individually when full detail is required. That is a concrete when-to-use and how-to-sequence instruction rather than implied usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description usefully adds that results are field-truncated when the user token is absent or under-permissioned, listing exactly which fields survive. It also discloses "Mindbody calls: 1", giving the agent a cost signal it could not get from annotations. It stops short of describing full response shape or pagination behavior, which keeps it below a 5.

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 permission caveat is front-loaded in a short paragraph and the field list is compact bullet form. "Get Staff — GET /staff/staff" mildly restates the name, but the endpoint reference and per-call cost line both earn their space.

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 nine-parameter read-only listing tool with no output schema, the description covers the permission-truncation case but omits what a fully authorized response contains and how results relate to the optional filter parameters. No output schema means the field list is a partial substitute for return-value documentation, leaving a real gap.

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%, with all nine parameters documented including the cross-parameter dependencies for locationId, sessionTypeId, and startDateTime. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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?

The description states a specific verb and resource ("Get Staff") and even pins the underlying endpoint, GET /staff/staff, so there is no ambiguity about what is being fetched. It does not, however, distinguish this from related siblings such as get_staff_appointments or find_likely_attendees, leaving the agent to infer the boundary.

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?

There is no guidance on when to call this versus alternatives, and no mention of the sibling tools that overlap in scope. The only conditional statement is about token permission levels, which is a response-shape caveat rather than a when-to-use rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds a genuinely useful piece of operational context, 'Mindbody calls: 1', which signals API quota cost, but it says nothing about pagination behavior, ordering, or what an unfiltered call returns across all staff and dates.

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?

Three short lines with the resource named first, then the endpoint, then the return summary, so the key information is front-loaded. There is mild redundancy in echoing the title verbatim as the opening fragment, but nothing is padded.

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 ten-parameter, zero-required read tool with no output schema, the description is minimal: it does not address the fact that every filter is optional, the default page size, or whether results are scoped to a site. Annotations and a fully covered schema carry most of the load, making it adequate but not complete.

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 every one of the ten parameters, including the defaults for startDate/endDate and the useSiteSettingsStaffName flag, is already documented in the schema. The description adds no meaning beyond that, which is the baseline 3 case rather than a deficiency.

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?

The description states a specific verb and resource ('Get Staff Appointments') plus the underlying endpoint and a one-line summary of the return shape ('a list of appointments by staff member'). This is clear enough to act on, but it never contrasts itself with nearby siblings such as appointment_openings, get_staff, or schedule_attention.

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?

Usage is only implied by the name and the phrase 'by staff member'; the description gives no explicit when-to-use, when-not-to-use, or alternative tool to pick instead. Nothing is misleading, but the agent must infer the selection criteria entirely from the tool name and the sibling list.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the paging budget (up to 10 inventory pages and 5 catalog pages, max 15), the truncation behavior of items vs matched, and that out-of-catalog barcodes are excluded and surfaced in notInCatalog. This is exactly the kind of API-level behavior an agent cannot infer from structured fields.

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-loads the core definition and then layers threshold logic, exclusion rules, and API budget. Dense but every sentence carries information; a few clauses (e.g. the parenthetical page math) could be trimmed.

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 no output schema, the description compensates by defining the returned fields (matched, items, notInCatalog) and their relationship. Combined with the call-budget disclosure, an agent has everything needed to call and interpret this tool correctly.

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 already 100%, so the baseline is 3, but the description adds meaning beyond it by explaining the interaction between threshold defaults, per-row ReorderLevel fallback, and how limit truncates items while matched stays complete. It reinforces rather than duplicates the 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 precise verb+resource+condition: retail products in the current catalog at or below their reorder point. It also distinguishes itself from the sibling inventory tool by noting 'Inventory has no category filter', so an agent can tell it apart from get_products_inventory.

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?

Gives clear operating guidance: use 'matched' for the true count rather than counting returned rows, and note that no category filter exists (pointing implicitly at other catalog tools). It stops short of naming a specific alternative tool or stating an explicit when-not-to-use condition.

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

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.

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

Annotations cover the safe-read profile, and the description goes well beyond by disclosing the large-read guardrail (>10000 profiles returns counts and credits until confirmLargeRead is true), the API call budget (1 per 200 profiles, 1 per 200 clients, at most 1001), and the important caveat that startedInRange misses memberships that have since ended. These are exactly the operational facts an agent needs before invoking.

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 the purpose and outputs, then alternatives, then cost, in a sensible order; there is essentially no filler. It is a single dense paragraph, so the alternative routing and the call-budget sentence are somewhat buried rather than visually separated.

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 eight optional parameters, no output schema, and an open-world read, the description supplies the output categories, the large-read behavior, and the temporal semantics that the schema alone cannot. The exact return shape (e.g. field names beyond byMembership and startedInRange) is only partly implied, which keeps it short of perfect.

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 100%, so the baseline is 3, but the description adds interpretive meaning the schema does not: the range/startDate/endDate window applies only to startedInRange while all other counts are as-of-today, and startedInRange is framed as a substitute for 'new members' with a known blind spot. It does not add much on top/top folding or membershipIds beyond the schema wording.

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 with scope: 'Active memberships at one site today', then enumerates the four outputs (member count, count per membership, unheld memberships, startedInRange). This is clearly distinguishable from get_memberships (name lookup) and the other summary siblings.

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 three alternatives with the condition that selects each: new_clients_summary for new clients/first visits, clients_at_risk for non-renewal, sales_summary for revenue. It also states an exclusion up front ('A snapshot of today, with no comparison or past date'), so the agent knows not to reach for it for trend questions.

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

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

Annotations already declare readOnly, idempotent and non-destructive, but the description goes well beyond them: it discloses the credit model, that every profile is read once regardless of sections, the 15,000-profile guard that returns only a count until confirmLargeRead is set, that inactive profiles are counted, and that compareTo costs nothing extra. The Mindbody call arithmetic (1 per 200 profiles, plus 1 for program names, 1 per listed client capped at 701) is unusually candid. It stops short of describing error conditions, so not a full 5.

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 what the tool returns, then cost/gating, then sibling routing — a sensible order with no filler sentences and no repetition of the title. It is dense and long, and the closing Mindbody call-count detail is crammed in as a run-on, but every clause carries decision-relevant 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 ten-parameter, two-section analytics tool with no output schema, the definition covers return contents, cost, large-read gating, comparison windows and alternatives. The only material gap is that nothing is said about what happens when a site is small, a range is invalid, or a section yields zero rows — minor for a read-only reporting call.

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?

The schema is fully documented at 100% coverage, so the baseline is 3. The description adds real value for two params the schema names only generically — it ties 'top' to the byHomeLocation/topReferralSources row counts and 'limit' to the newest-first contact-detail listing — and explains the firstVisitDetails credit charge. But most of the ten parameters (range, startDate/endDate, siteId, include) are not touched on beyond what the schema already says.

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?

Names both sections it returns (firstVisits and newClients) and states exactly what each contains — first booked class/appointment clients with contact details and consent flags, and profiles created in range with prospects, home locations and referral sources. It also scopes the tool to one site, which an agent can hold against the multi-topic siblings without reading either 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?

Explicitly routes four neighbouring questions elsewhere by name: membership_summary for members, late_cancel_count for late cancels, class_attendance_summary for attendance, and sales_summary for revenue. It also adds two non-obvious usage rules — that omitting a section saves no credit, and that a read above 15,000 profiles needs confirmLargeRead — which change how an agent should call it.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so safety is covered. The description goes further with a real cost model: 1 call per 200 sales, cap of 10000 sales per range, parallel fetching, doubling by compareToPrevious, cached location/category lookups, and 1 call per 20 topClients (max 104). It also defines currency and the netSales/collected distinction, which are behavioral facts not present in 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 and the get_sales routing rule are front-loaded, and the metric definitions and call-cost math are compressed into single clauses with no filler. It is a dense wall of text rather than structured into bullet-like segments, which slightly hurts scanability for a description this feature-rich, but no sentence is expendable.

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 no output schema and 9 parameters, the description carries the return-value burden and does so by enumerating every metric and breakdown section plus currency and netSales/collected definitions. The remaining gap is that it does not describe the response's overall shape (e.g. how totals nest relative to breakdown arrays) with no output schema to fall back on.

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 100%, so the baseline is 3, but the description adds interpretation the schema lacks: what compareToPrevious does to call volume and how it aligns periods, that locations accepts names or IDs where get_sales cannot, and what netSales versus collected actually mean. The only gap is that it doesn't tie the top-N folding or interval auto-selection back to parameters, though the schema already documents those.

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 ('answers revenue and sales questions', 'reads every sale in a date range') and enumerates exactly what comes back: totals, byPeriod, topItems, byCategory, byPaymentMethod, byLocation, optional topClients and comparison. It explicitly distinguishes itself from get_sales by returning 'a compact summary instead of raw sales' and by supporting location filters get_sales cannot.

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?

Gives an explicit routing rule: 'Use this instead of get_sales for any "how much did we sell or make" question', with the inverse implied (get_sales for raw line items). It also flags the capability gap (location name/ID filtering) that makes this the only option for that case, so the agent has both a positive and a negative selector.

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

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

Annotations already cover read-only, idempotent and open-world. The description adds two things annotations can't: the local-time basis for "not started" and an explicit call budget (one cached site lookup, then 1 per 200 classes, capped at 11). The API-cost disclosure is a strong addition for an open-world tool.

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?

Two dense sentences with the returned content front-loaded before alternatives and cost. No filler. The headline phrase is slightly cryptic and has to be decoded by the clause that follows, which costs a little immediate clarity.

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?

There is no output schema, so the description carries the burden of saying what comes back, and it does so by naming all three lists. Combined with the call-budget note and local-time clarification, an agent has everything needed to call this correctly and know what to expect.

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 100%, so every parameter is already documented, and the baseline applies. The description adds only indirect meaning — that minSpotsLeft feeds the 'open spots' list and that dates are interpreted in studio local time — without covering limit, siteId, or date-window interaction beyond what the schema says.

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?

The opening line is a bit oblique ("What on a short schedule needs a person"), but the colon-clause enumerates exactly what the tool returns: future classes with open spots, classes with a waitlist, and classes with a substitute teacher. That enumeration distinguishes it from find_classes and class_attendance_summary, which are named.

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 explicitly routes the agent elsewhere: find_classes to browse the schedule or look for open spots, class_attendance_summary for fill rates and busiest times. That is real when-to-use guidance. It doesn't state when-not to call it or any prerequisites, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the agent knows this touches an external system and isn't a pure read. The description adds meaningful context beyond that: a 30-second throttle, a no-loop warning, and the downstream consequence of a 'connected' result. What's missing is any note on what a non-connected/pending/expired status means for the caller.

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?

Two tight sentences, front-loaded with the core action and followed by the operational constraint. The parenthetical throttle note is compact and earns its place. Slightly dense phrasing ('the user reconnects or starts a new conversation') takes a moment to parse but carries real guidance.

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 no output schema, the description does describe the return content (recent requests plus connected sites) and the conditional check on one pending request. For a one-optional-param tool this is largely sufficient, though the vocabulary of possible connection states is left undefined.

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 100% and the single optional siteId is documented in the schema as 'Only this site (optional).' The description never mentions siteId or what narrowing to one site does to the response, so it adds nothing beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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?

The description opens with a specific verb+resource: it lists recent studio connection requests and connected sites, and checks one pending Mindbody request. That is clearly distinct from the write-oriented connect_studio sibling, though it never names that sibling to make the split explicit.

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 gives concrete operational guidance: call at most once every 30 seconds and don't loop. It also explains the follow-up action when a request reports connected (reconnect or start a new conversation so Mindbody tools load). It stops short of explicitly saying 'use connect_studio to initiate a new connection', which leaves one sibling routing decision implied.

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

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

Annotations already establish this as a safe, idempotent read, and the description still adds substantial behavior: the exact call budget per range (15 sales pages + 10 class pages, doubled when comparing, capped at 51), a cached site lookup, and the partial-result rule where short totals are named and change is omitted. It also defines metric semantics that matter for interpretation (netSales is after discounts before tax; collected is payments received).

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 what the agent gets before any caveats, and every sentence carries information (metrics, siblings, metric definitions, partial behavior, cost). The style is telegraphic and the call-budget sentence packs three facts together, which slightly raises parsing effort.

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?

There is no output schema, and the description compensates by enumerating the returned metrics and defining the two ambiguous ones. Combined with the partial-result rule and the call budget for a fan-out tool with up to 51 calls, an agent has everything needed to call it and to set expectations about cost and completeness.

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 100%, so baseline is 3, but the description adds real cost semantics for compareToPrevious (the call budget doubles) and reinforces that range and startDate/endDate are mutually exclusive. The range presets themselves gain no new meaning beyond the enum descriptions.

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?

"How the studio did in one period" is immediately qualified by the exact metric list it returns: sale count, net sales, amount collected, average sale, unique clients, class fill. It explicitly scopes out siblings (sales_summary and class_attendance_summary handle breakdowns) and out of scope content (no line items, no class rows), so an agent can separate it from the other summary tools without opening a 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?

It names two concrete alternatives with the condition that selects them (breakdowns go to sales_summary and class_attendance_summary) and rules out line-item and class-row use. It does not address the other period-summary siblings such as membership_summary or new_clients_summary, so the routing 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.