mindbody

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

Annotations only supply destructiveHint=true, so the description carries the rest and does it well: no card is charged, apply_payment only applies an existing pricing option and defaults to true, test:true is a dry-run, and a staff user token is required. That is exactly the billing/auth behavior an agent needs before committing a write.

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?

Five tightly packed sentences with the core action front-loaded and prerequisites, billing, and dry-run notes following in priority order. The trailing 'Mindbody: POST /appointment/addappointment' endpoint reference is the one mildly expendable clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers the critical unknowns (auth token, dry-run, billing side effects, prerequisite lookup). It does not touch return values or waitlist behavior, but the essentials for correct invocation are present.

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 goes beyond the schema by clarifying that no card is charged and that apply_payment is limited to pricing options already on the client's account, plus restating dry-run semantics for test. Marginal but real added meaning over the structured fields.

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 plus the actors involved ('Book an appointment for a client with a staff member at a location'), which cleanly distinguishes it from mindbody_update_appointment, mindbody_list_staff_appointments, and mindbody_add_client_to_class.

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 the agent to mindbody_list_bookable_items as the prerequisite slot-finding step, which is the main usage decision. It stops short of stating when not to use this tool (e.g. reschedule vs update), so it is clear context without full exclusions.

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 carry destructiveHint, so the description does the heavy lifting: it discloses that required fields are site-dependent and reported by Mindbody, that no card/billing data is accepted, and that test: true commits nothing. That is meaningful behavioral context 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?

Three compact sentences, front-loaded with the core action and requirement, then the data restriction, then the dry-run and endpoint. No filler sentences.

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?

Given 21 parameters, no output schema, and thin annotations, the description covers the critical creation constraints and dry-run behavior well. Its one gap is not hinting at what a successful call returns (e.g., the new client identifier).

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 21 parameters are already documented, including the test flag's dry-run semantics. The description reinforces the required fields and the no-billing-data constraint but adds little parameter detail beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a new client record') and is clearly separable from siblings like mindbody_update_client, mindbody_list_clients, and mindbody_add_client_to_class. It also names the underlying endpoint, removing any ambiguity about the operation.

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 actionable context: first/last name are required, the site may demand more, and test: true performs a validate-only dry run. It does not explicitly compare against mindbody_update_client or state when *not* to use this tool, so it stops short of the top tier.

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 carry destructiveHint=true, so the description adds real value: no payment is taken by default, require_payment forces a usable pricing option, and test:true validates without committing. It also discloses reversibility ('Undo from the Mindbody front desk'), which is important for a write operation.

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?

Five tight fragments, front-loaded with the action and variant, then payment behavior, undo path, dry-run, and endpoint. Every sentence adds distinct operational value with no redundancy.

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 only a destructiveHint annotation, the description still covers payment, dry-run, waitlist, and reversibility well. Minor missing pieces like confirmation-email behavior (covered only in the schema) keep it just under 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 documents all seven parameters, making 3 the baseline. The description reinforces the semantics of require_payment and test and clarifies the default (no pricing option needed), but adds little beyond the schema's own parameter 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?

The description states a concrete verb and resource — booking a client into a class — and clarifies the waiting-list variant in the same sentence. It clearly differs from mindbody_add_appointment by the 'class' resource, though it does not explicitly name that sibling.

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 implied context (booking vs waitlist, dry-run via test:true, undo via front desk) but never states when to prefer this tool over the appointment or list siblings. The guidance is present but left for the agent to infer.

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=true, so the safety profile is covered. The description usefully adds that the payload is a roster of booked clients with sign-in and late-cancel status, plus the underlying endpoint, but says nothing about pagination, result size, or authorization.

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?

One front-loaded sentence carrying the purpose plus the roster clarification, followed by the API endpoint reference. No filler; every clause earns its place.

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?

No output schema exists, so the description carries the burden of describing the return, and it does so adequately by naming the roster and the status fields. It leaves secondary details (pagination, whether unbooked visits appear) unspecified, which is a minor gap for a two-parameter read tool.

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%: class_id is documented with its source (mindbody_list_classes) and last_modified_date with ISO 8601 format and an example. The description adds no parameter meaning beyond that, 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?

Specific verb and resource ('Get one class with its visits') plus an immediate gloss that disambiguates the ambiguous term 'visits' as the client roster with sign-in/late-cancel status. It is clearly distinguishable from sibling list tools such as mindbody_list_client_visits and mindbody_list_classes.

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 by the phrasing (fetch the roster for a single class), but there is no explicit statement of when to prefer this over mindbody_list_client_visits or mindbody_list_class_schedules, and no prerequisites or exclusions are given.

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=true, so the safe-read profile is covered without the description. The description adds the useful semantic note that a balance can be owed or held in credit, but says nothing about pagination behavior or whether results are capped despite listing limit/offset.

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 short sentences, front-loaded with the core action and followed by the API mapping. Nothing redundant or 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 read-only, fully schema-documented tool with no output schema, the description covers purpose, scope, and the key optional date dimension. Minor omission: no mention of what the balance payload contains or pagination limits, though the safety profile is handled by annotations.

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 client_ids, balance_date, limit, offset and class_id are all documented in the schema. The description reinforces the client_ids and balance_date semantics but adds no detail on class_id or paging beyond what the schema states. 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?

Specific verb+resource ('Get the account balance for one or more clients') with a clarifying gloss ('what they owe or hold in credit') and an explicit optional dimension (as of a date). No sibling tool touches client balances, so the agent can pick it out immediately.

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 by the description — fetch balances for given client ids — but there is no explicit when-to-use/when-not guidance or reference to an alternative tool for related financial or client data. Adequate minimum, clear gap.

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=true, so the safe-read profile is covered. The description adds that this is an availability-discovery step preceding booking, which is useful, but says nothing about the volume/shape of results, pagination behavior, or how availability records are structured — relevant for a 10-param search. With annotations carrying safety, this is an adequate-but-thin addition.

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 sentences, zero filler: the capability and its scope come first, then the workflow pointer and the underlying endpoint. Nothing is redundant with the name or title.

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 search tool with no output schema, the description effectively summarizes what is returned (staff / location / time windows) and when to call it. Missing is any note on result volume or pagination handling despite limit/offset being exposed, which is a minor gap given the otherwise thorough 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%, and the schema itself documents defaults, formats (ISO 8601 examples), and per-field intent for all 10 parameters. The description adds no parameter-level detail beyond naming session types, so the 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 specific verb and resource ('Find appointment availability') and then enumerates the result dimensions — staff, location, time window. This scope is clearly distinguishable from siblings like mindbody_list_staff_appointments or mindbody_list_services 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?

Explicitly positions the tool in a workflow: 'Use before mindbody_add_appointment,' naming a concrete alternative/next step. It gives clear context but no when-not guidance (e.g., it never says to prefer mindbody_list_staff_appointments for reviewing already-booked appointments), so it stops short of full routing.

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 supply readOnlyHint=true, so the description carries the rest of the burden and does useful work by naming the exact result payload, which matters because there is no output schema. It stops short of disclosing pagination behavior (limit/offset defaults live only in the schema) or the client_id side effect noted there (client-specific pricing).

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 clauses: the scope/range constraint first, the returned payload second. Every element earns its place and the endpoint reference is a compact trailing tag.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-filter read tool with no output schema and full schema coverage, the description is nearly complete: it conveys scope, result contents, and the upstream endpoint. The only material omission is any mention of pagination semantics, which is where an agent could stumble on large date ranges.

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 all 14 filters, so the schema already documents each parameter's semantics and defaults. The description adds only the generic notion of a 'date range', which is the baseline-3 case where structured data 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?

States a specific verb and resource ('List scheduled class occurrences') and enumerates the data returned — time, teacher, location, capacity, booked/waitlist counts, cancellation status — plus the underlying Mindbody endpoint. The word 'occurrences' implicitly separates it from mindbody_list_class_schedules (recurring templates), but that distinction is left for the agent to infer rather than stated.

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 date-range framing gives implied context for when the tool applies, but there is no explicit when-to-use vs mindbody_list_class_schedules or mindbody_get_class_visits, and no statement of prerequisites or exclusions. Usage must be inferred from the filters and the returned fields.

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?

readOnlyHint=true already declares this as a safe read, so the safety profile is covered. The description adds the useful semantic that results are recurring templates rather than dated occurrences, but says nothing about pagination behavior or response shape.

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 compact sentences, front-loaded with the disambiguating definition followed by the endpoint. No 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 partially compensates by enumerating the fields returned (days, times, teacher, location, date span), and the readOnly annotation covers safety. Adequate for a 9-param optional-filter list tool, though pagination/return-size behavior is left to the 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 all nine filters (limit, offset, dates, staff/program/location/session_type/class_schedule ids) are already documented. The description's mention of 'days, times, teacher, location and date span' loosely echoes the filterable dimensions but adds no syntax or default detail 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?

States a specific verb and resource ('List recurring class schedules') and immediately disambiguates the resource with 'the templates that generate class occurrences', which cleanly separates it from the sibling mindbody_list_classes (actual occurrences). The endpoint reference confirms 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?

The template-vs-occurrence framing implies when to prefer this tool over mindbody_list_classes, but there is no explicit when-to-use statement, no exclusions, and no named alternative. Usage must be inferred from the parenthetical.

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=true, so the safety profile is covered. The description usefully adds that these are auto-renewing memberships and that results include remaining counts and expiry, but it does not describe pagination behavior or how 'active' is determined beyond 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?

A single front-loaded sentence delivering the resource, a clarifying synonym, the returned fields, and the backing endpoint — no wasted prose.

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 partially compensates by naming the return fields (remaining counts, expiry). Combined with 100% schema coverage and a readOnly annotation, an agent has enough to call it correctly, though return-shape detail is thin.

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 five parameters (including client_id's RSSID note and the location_id/cross_regional_lookup interaction) are already documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List a client's active memberships') and clarifies the domain term with 'auto-renewing pricing options', which lets an agent distinguish it from siblings like mindbody_list_client_visits or mindbody_get_client_account_balances.

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 by the resource (look up a client's memberships) but there is no explicit when-to-use/when-not guidance and no mention of alternative tools for related data such as balances or visits. The 'active' qualifier is the only scoping hint.

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=true, so the safety profile is covered; the description still adds the staff-token auth requirement and the 20-id cap, which are meaningful operational constraints. It does not discuss pagination behavior or result ordering, which keeps it short of 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?

A single front-loaded sentence covering modes, limits, payload, and auth, followed by the underlying endpoint. No 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?

For a 7-parameter read tool with no output schema, the description covers the two access patterns, the id cap, the auth requirement, and the returned field categories. Pagination is implicitly handled by limit/offset in the schema but not called out in prose, a minor 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%, so every parameter is already documented in the schema. The description's mention of the max-20-ids limit and name/email matching merely echoes those schema constraints, adding no new syntax or format detail.

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 (search/fetch) plus resource (client records) and the two selection modes (name/email text or up to 20 client ids), plus what the record contains. This clearly separates it from siblings like mindbody_add_client and mindbody_update_client.

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 context: it is the read path for client records, and it states the prerequisite 'Requires a staff user token.' However, it never names an alternative tool or a when-not condition, so the routing guidance is implied rather than explicit.

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?

With readOnlyHint=true already declaring this a safe read, the description adds useful scope context: it returns both past and scheduled (future) visits spanning class and appointment attendance, and cites the underlying endpoint GET /client/clientvisits. It does not, however, describe return shape or pagination behavior beyond what the schema already states.

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 sentences, zero waste, front-loaded with the core purpose and the scope of returned records, then the endpoint reference. Nothing to trim.

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, 8-parameter list tool with 100% schema coverage and no output schema, the description covers purpose, temporal scope, and the result type (class/appointment attendance). It is nearly complete, missing only a note on result format/pagination volume, which the schema partially covers via offset/limit descriptions.

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 parameter (limit, order, offset, dates, unpaids_only, cross_regional_lookup, client_id) is already fully documented in the schema. The description only re-states the date-range and unpaid filters, adding no syntax or semantics beyond the structured fields. Baseline 3 for full-coverage schemas is correct.

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 ('List a client's ... visits') and scopes it precisely ('past and scheduled visits (class and appointment attendance) in a date range'). This is clearly client-scoped, which helps distinguish it from the class-oriented sibling mindbody_get_class_visits, but it never names or explicitly routes away from any sibling, so it stays at a 4.

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: an agent can infer 'use this to see one client's attendance history'. There is no explicit when-to-use/when-not-to-use guidance and no alternative named (e.g. mindbody_get_class_visits for class-level attendance, or mindbody_list_client_memberships for membership data). The 'optionally only unpaid ones' note hints at a filtering use case but is not framed as 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?

readOnlyHint=true already establishes this as a safe read, so the description need not carry the safety profile. It usefully adds what the payload contains (address, phone, amenities) and the underlying endpoint (GET /site/locations), but says nothing about auth requirements, rate limits, or pagination behavior beyond what the schema states.

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 sentences, zero padding, front-loaded with the primary purpose and the returned fields before the endpoint reference. Every sentence earns its place.

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 helpfully enumerates the key returned fields and the pagination parameters are fully documented in the schema. It is nearly complete for a simple list tool, missing only guidance on differentiating from mindbody_list_sites.

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 both pagination parameters carry defaults and a TotalResults pointer in the schema, so the schema does the heavy lifting. The description adds no parameter-level meaning, which matches the baseline 3 for well-documented schemas.

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 verb (List) and resource (business's locations, glossed as studios/branches) and previews the returned fields (address, phone, amenities). It does not explicitly differentiate from the nearest sibling, mindbody_list_sites, 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?

"Location ids are needed to book appointments" gives a concrete downstream reason to call this tool, which is more than pure implication. However, it never names an alternative (e.g. list_sites) or states when-not to use this tool, so guidelines remain suggestive rather than explicit.

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=true, and the description's 'Read only' merely restates that. It does add the useful scoping fact that results are limited to completed sales within a date range, but says nothing about pagination behavior, permissions, or rate limits beyond what the schema already documents.

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 front-loaded sentence carries the operation, scope, returned content, safety, and upstream endpoint. No filler and no redundancy.

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 usefully names what each sale contains (items, payments, client), and pagination semantics live in the schema. Only minor gaps remain, such as whether non-completed/voided sales are excluded and any auth expectations.

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 six parameters (limit, offset, sale_id, payment_method_id, start/end_sale_date_time) are fully documented in the schema. The description's 'date/time range' only loosely gestures at the start/end pair and adds no format or interaction detail 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?

States a specific verb and resource ('List completed sales at the site') plus the returned content (purchased items, payments, client) and the scoping dimension (date/time range). No sibling tool covers sales, so the definition is unambiguous within the toolset.

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 'completed sales ... in a date/time range' phrasing implies when the tool applies, and 'Read only' sets the operation type, but there is no explicit when-not guidance and no alternative tool named. Usage is inferred rather than stated.

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?

readOnlyHint=true already declares the safety profile, and the description largely repeats this with “Read only.” It does add value by disclosing the underlying endpoint (GET /sale/services) and the shape of returned attributes, which helps set expectations. However, it omits pagination behavior despite 12 params including limit/offset, and adds no auth or rate-limit context.

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 tightly packed sentences with no filler: the resource and returned fields come first, then the read-only note and endpoint. Every clause 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 12-parameter read-only listing tool with full schema coverage and no output schema, the description covers the resource, the returned fields, and the safety profile. It would be complete if it addressed pagination (since limit/offset exist) or clarified its relation to list_sales, but the schema compensates for the former.

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 12 parameters (including the non-obvious location_id tax computation and per-staff pricing) are already fully documented in the schema. The description adds no parameter-level detail beyond the schema, 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?

The description states a specific verb and resource (“list the pricing options”) and resolves Mindbody's ambiguous “services” terminology by equating it with class packs, drop-ins, and intro offers. It also names the returned attributes (price, online price, count, expiry). It is clear, but stops short of explicitly contrasting itself with the nearby sibling list_sales, which an agent might otherwise confuse with it.

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 says what the tool lists but gives no guidance on when to choose it over list_sales, list_bookable_items, or the other catalog siblings. There is no mention of prerequisites, typical scenarios, or exclusions; the agent must infer usage from the resource name alone.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lower burden. It adds the underlying endpoint (GET /site/sessiontypes) and the note that ids drive availability/booking, but says nothing about pagination behavior or result completeness. Adequate, not rich.

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 terse clauses with zero padding: what it lists, why the results matter, and the backing endpoint. The definition of the resource is front-loaded so an agent can classify the tool immediately.

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 zero-required-parameter read-only list tool with full schema coverage, the description covers purpose, domain meaning, and endpoint. The only modest gap is that no output schema exists and the description doesn't sketch the returned shape (ids, names), though that is minor for a simple list.

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, online_only, and program_ids are all fully documented in the schema. The description adds no syntax or format detail beyond that, so the 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 specific verb and resource ('List the session types') and goes further to define the resource in domain terms ('the bookable kinds of class or appointment, e.g. 60-min massage'). This meaningfully distinguishes it from nearby siblings like list_classes, list_services, and list_bookable_items.

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 hints at the use case ('session type ids drive appointment availability and booking'), which implies the tool is used to resolve ids before booking, but it never states when to prefer this over list_classes/list_services/list_bookable_items, nor any exclusions or prerequisites.

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?

With readOnlyHint=true already declaring the safety profile, the description adds useful scope context: results are limited to sites the developer account can access, and passing site_ids returns more detail per site. It does not mention pagination behavior, but that is covered by the 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?

Two tight sentences with the core purpose front-loaded and no filler. The trailing 'Mindbody: GET /site/sites' is marginally redundant with the resource name but confirms the upstream endpoint.

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 no-required-param, read-only list tool with no output schema and full schema coverage, the description covers scope, the API-key use case, and the two filtering modes. Return shape is left to the reader but is not critical here.

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 limit/offset/site_ids are all documented in the schema, including the detail-level difference for site_ids. The description adds no parameter meaning beyond that 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?

States a specific verb (List) and resource (Mindbody sites/businesses) plus the scope of access, and clarifies what a 'site' is via the parenthetical '(businesses)'. An agent can distinguish it from siblings like mindbody_list_locations or mindbody_list_clients.

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?

Offers a concrete use case ('A cheap way to confirm the API key works') and notes the alternate mode for retrieving specific site details. It lacks explicit when-not guidance or named alternatives, but the context for calling it is clear.

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 declare readOnlyHint=true; the description adds a genuinely useful auth behavior not in structured data: 'Without a staff token only public fields return.' It also cites the underlying endpoint (GET /staff/staff). It does not describe pagination or rate limits, but the auth caveat is meaningful added context.

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 tight sentences with no filler: identity/scope first, the two filtering modes second, the auth caveat and endpoint last. Every sentence carries load and the key constraint is 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 7-parameter, zero-required read tool with no output schema, the description covers the main query modes and one important behavioral caveat. Return-field detail is arguably needed since no output schema exists, but the annotations plus schema cover most of what an agent needs to call it 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 description coverage is 100%, so every parameter is already documented, including the session_type_id/location_id/start_date_time co-dependency. The description restates that dependency rather than adding syntax or constraint detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List staff members') and clarifies the domain meaning with '(instructors, practitioners)', so an agent knows what a staff record is. It does not explicitly distinguish itself from the closest sibling, mindbody_list_staff_appointments, but the resource 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?

Gives concrete usage conditions: filter by role, or use the availability pattern with session_type_id + location_id + start_date_time together. It does not name alternative tools or state when not to use this one, 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description adds the endpoint mapping but no pagination behavior, rate limits, auth requirements, or empty-result handling. It discloses nothing beyond what the annotations and schema already convey.

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 front-loaded sentence that identifies the resource, then the filters, with no filler. The trailing "Mindbody: GET /appointment/staffappointments" is marginally useful for debugging but is not strictly required for tool selection.

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, all-optional list tool with no output schema, the description covers purpose and filters but says nothing about result set shape, paging defaults (limit 100 / offset 0), or ordering. There is no output schema to rely on, so the omission of return-side expectations leaves a modest 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%, so the baseline is 3 and the schema carries the burden. The description restates the staff/client/appointment-id filters but omits location_ids and pagination parameters entirely and adds no format or default detail 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?

States a specific verb and resource ("List booked appointments") plus the scope it covers ("in a date range, by staff member, client or appointment id — the appointment book"), so an agent can immediately separate it from the sibling write tools mindbody_add_appointment and mindbody_update_appointment. The underlying endpoint (GET /appointment/staffappointments) is also named, anchoring the resource unambiguously.

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 names the filter dimensions, which implies when the tool applies, but never states when to prefer it over alternatives such as mindbody_get_class_visits or mindbody_list_client_visits, nor any prerequisite (e.g., required staff/client/location context). Usage is only 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?

Adds real value beyond the lone destructiveHint annotation: it discloses the auth requirement, that only a fixed set of fields are mutable, that status changes are a distinct operation, that a dry-run mode exists, and why cancel is excluded (a late cancel can charge the client). It stops short of describing the response or whether email sends are side effects by default.

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 core action, then constraints, dry-run, auth, and endpoint. Every sentence carries information; no 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?

For a 9-parameter mutation tool with no output schema and minimal annotations, the description covers mutability scope, status actions, dry-run, and auth. It lacks only details on return payload/confirmation and default email behavior, which are minor gaps.

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 goes further by asserting the listed fields are the exhaustive set Mindbody permits changing and by framing test: true as a validation-only dry run. That meaning is complementary to, not a restatement of, 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?

States a specific verb+resource (reschedule/edit an appointment) and enumerates exactly what can change (start/end time, staff, session type, notes) plus the status transitions. This cleanly distinguishes it from sibling mindbody_add_appointment, which creates rather than edits.

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 context for use, states prerequisites (staff user token), a dry-run path (test: true), and explicitly rules out cancel/late-cancel with a reason. It does not, however, name the sibling tool an agent should use instead for cancellation, so the routing guidance is incomplete.

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 give destructiveHint:true, and the description adds substantive behavior beyond that: partial-mutation semantics (only passed fields change), a hard restriction (no card/billing data accepted), the default-on cross-regional propagation, and a validate-only dry-run mode. These are real behavioral facts not derivable from the annotation.

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?

Dense but front-loaded: the mutation contract comes first, then constraints, then the two behavioral flags. Every sentence carries information, with only the trailing endpoint reference being near-redundant.

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 23-param mutation with full schema coverage and an existing destructiveHint annotation, the description supplies the missing behavioral context: partial update, data restrictions, propagation default, and dry-run. No output schema exists, but a write tool's return shape is not strictly needed here.

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 3 is the baseline. The description earns above baseline by explaining the partial-update contract and clarifying cross_regional_update's default and side effect, adding meaning the per-field schema text does not convey.

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 ('Update fields on an existing client record'), and the partial-update clause ('only the fields you pass change') sharpens the scope. It is clearly distinct from mindbody_add_client, though it does not name any sibling 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 offers useful operational guidance — partial-update semantics, the dry-run via test:true, and the cross_regional_update propagation — but never states when to choose this tool over alternatives like mindbody_add_client or update_appointment. Usage is implied rather than declared.

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