Acuity Scheduling MCP by usefulapi

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

readOnlyHint=true already tells the agent this is a safe read, and the description confirms a non-mutating list of time slots. It adds the scope constraint (group classes only) but says nothing about pagination, result ordering, or how empty/full months are represented beyond the includeUnavailable param in 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 sentences, zero waste, with the core purpose front-loaded and the REST endpoint noted as secondary reference. Nothing extraneous.

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 list tool with fully documented parameters and no output schema, the description covers what is being returned (monthly class time slots) adequately. Minor omission: no hint about result shape or how 'unavailable' entries differ when includeUnavailable is 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%, so all four parameters (month, timezone, appointmentTypeID, includeUnavailable) are already documented in the schema with formats and behavior. The description adds no parameter-level 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?

States a specific verb ('List') and resource ('group class time slots') and scopes it to class-type appointment types, which meaningfully distinguishes it from sibling availability tools like acuity_availability_dates and acuity_availability_times. It never names those siblings explicitly, but the class-type qualifier carries the differentiation.

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 'for class-type appointment types' qualifier, which tells the agent this is the availability variant for classes rather than times or dates. However, it never states when to prefer this over the sibling availability tools or any prerequisites beyond the schema's required 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 tells the agent this is a non-destructive read, so the safety profile is covered. The description adds only the REST endpoint provenance, which is consistent with the read-only annotation but discloses nothing new about rate limits, auth requirements, or whether the returned dates are filtered by existing bookings.

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 with zero filler, and the operation scope is front-loaded ahead of the endpoint reference. Nothing is repeated and no sentence is 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 simple read-only helper with a fully documented 4-parameter schema and annotations covering safety, the description is essentially sufficient. It could say slightly more about the return shape (e.g. a list of YYYY-MM-DD strings) since no output schema exists, but the phrase 'List dates' largely covers it.

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 month, timezone, calendarID, and appointmentTypeID are all fully documented in the schema itself. The description restates the appointment-type and month concepts but adds no format, default, or interaction semantics 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 (List), resource (dates), and two scoping constraints (in a month, for an appointment type), plus the underlying REST endpoint GET /availability/dates. The resource noun 'dates' inherently separates it from acuity_availability_times and acuity_availability_classes without needing to name 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?

Usage is implied by the resource and scope ('in a month', 'for an appointment type'), so an agent can infer when this applies versus the times/classes variants. However, there is no explicit when-to-use guidance, no prerequisites, and no statement of when to prefer acuity_availability_times instead.

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 a safe read operation, so the bar is lower. The description is consistent with that and adds the underlying REST endpoint, but discloses nothing further about rate limits, pagination, or whether empty days return an empty list versus an error.

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, front-loaded sentences with no filler. The trailing REST endpoint note is mildly useful for orientation but does not help an agent select or invoke the tool.

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

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

For a simple read-only 4-parameter tool with full schema coverage and annotations, the description covers what the tool does and the scoping constraints. With no output schema, a hint at the return shape exists ('time slots'), though its format is left unstated.

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 of 3 applies. The description restates the date and appointment-type scoping already documented in the schema, and says nothing about timezone or calendarID, adding no meaning 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 available time slots') scoped by date and appointment type, so the agent knows what it returns. However, it does not distinguish itself from its closest siblings acuity_availability_dates and acuity_availability_classes, which also return availability data.

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?

No guidance on when to use this versus acuity_availability_dates or acuity_availability_classes, nor any prerequisites or exclusions. Usage is only implied by the word 'availability' in the name and description.

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 destructiveHint=true, so the description carries the rest and does well: it discloses that the calendar is modified and that cancellation emails are sent unless suppressed, which is a non-obvious side effect. It stops short of noting auth/permission implications beyond the indirect hint from the admin parameter.

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, with the action and its mutation/email consequences front-loaded and the API endpoint last. Every sentence adds information with 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 4-parameter destructive mutation with no output schema, the description covers the action, the side effects, and the underlying endpoint. It could go further on whether cancellation is reversible or what happens to the freed slot, but is largely sufficient for correct invocation.

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 id, admin, noEmail, and cancelNote fully. The description's 'unless suppressed' only loosely gestures at noEmail and adds no syntax or format detail beyond the schema, 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 ('CANCELS an existing appointment') and distinguishes itself from siblings like acuity_reschedule_appointment by naming the destructive outcome. The REST mapping (PUT /appointments/{id}/cancel) adds precision about what operation this is.

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 purpose, but there is no explicit when-to-use vs. when-not guidance and no mention of alternatives (e.g., prefer acuity_reschedule_appointment when the client wants a new time rather than outright cancellation). The agent must infer the routing decision.

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 destructiveHint=true; the description adds real context beyond that by disclosing the mutation target ('MODIFIES the calendar'), the email side effect with its suppression caveat, and the underlying REST call. It stops short of stating whether availability is validated or what happens on slot conflict, but the safety-relevant behavior is well surfaced.

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, front-loaded with the core action, then side effects, then the API mapping. No filler and nothing buried.

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 mutation with a fully documented schema and no output schema, the description covers purpose, mutation scope, and side effects adequately. It could say more about prerequisites (e.g., that a valid appointmentTypeID and open slot are needed, or that admin=true skips availability checks), but nothing critical 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 all 12 parameters are already documented in the schema (including admin's bypass semantics and noEmail's suppression behavior). The description's 'unless suppressed' phrase adds only marginal gloss over what the schema states, so 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 ('CREATES a new appointment') and immediately disambiguates with 'books a client into a time slot', which is not obvious from the name alone. The sibling tools (cancel, reschedule, get, list) are all distinct operations, and this description makes clear it is the creation path.

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: the agent can infer this is the tool for booking a new slot, and 'unless suppressed' hints at the noEmail control. However, there is no explicit when-to-use guidance relative to alternatives such as acuity_reschedule_appointment (for moving an existing appointment) or acuity_create_client, so routing must be inferred from the name.

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 safety profile (destructiveHint=true), and the description adds that this is an additive write via POST /clients. However, it never addresses what happens on duplicate clients, whether the record is immediately visible to booking, or what the caller gets back, which matters for a mutation 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?

Three short, front-loaded sentences with the action first. The second sentence ('This ADDS data') is mildly redundant with 'CREATES' but usefully signals a mutation versus a read.

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 create tool with no output schema and no return-value documentation, the agent cannot tell what identifier comes back or how to verify success. The essentials (what it does, that it is a POST write) are present, but side-effect and response expectations are 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% and the required fields (firstName, lastName) are already marked in the schema, so the description need not repeat them. It adds nothing about email/phone/notes semantics, so 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 ('CREATES a new client record in the account's client list') and even names the underlying REST operation (POST /clients). This clearly separates it from acuity_list_clients, though it does not call out that 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?

There is no guidance on when to create a client versus looking one up first (e.g., checking acuity_list_clients to avoid duplicates) or any preconditions like required account permissions. Usage is only implied by the verb.

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 adds the REST mapping (GET /appointments/{id}), which is useful context for matching against the API, but says nothing about failure behavior for a nonexistent id or the shape of the returned record.

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 with the core action front-loaded and the API endpoint appended for reference. No filler or redundant restatement of the 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 one-parameter read tool with full schema coverage and a readOnly annotation, this is nearly sufficient. The remaining gap is that no output schema exists and the description does not indicate what the returned appointment contains or what happens when the id is not found.

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 single 'id' parameter is fully documented in the schema itself. The description's 'by its id' only restates that, adding no format, range, or lookup semantics beyond the structured field, 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 ('Get a single appointment') plus the lookup key ('by its id'), which implicitly distinguishes it from acuity_list_appointments. It does not name the alternative tool explicitly, but the singular/plural contrast is clear enough to select correctly.

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: call this when you already have an appointment id and need the single record rather than a list. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the routing from the sibling names.

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 goes further by specifying that it is the *authenticated* account (implicitly requiring a valid credential) and by naming the concrete fields that come back. It stops short of describing rate limits, error behavior, or auth failure modes, but adds genuine context beyond 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?

Two short sentences, front-loaded with the core purpose and followed by the concrete return fields plus the underlying REST endpoint. Every clause earns its place with 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 zero-parameter read tool with an empty schema, the description is nearly sufficient: it names the resource, the auth scope, and the fields returned, which partially compensates for the missing output schema. It could be marginally stronger by stating that it always returns a single account object rather than a 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The brief field list in the description is useful but does not map to any input.

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 (Get) and resource (authenticated Acuity account's profile), and even enumerates the returned fields (name, email, timezone, plan, currency). This clearly distinguishes it from every sibling, all of which operate on appointments, clients, calendars, or catalog data rather than the account itself.

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 implies usage ('authenticated account's profile') but never says when to reach for this tool or how it relates to siblings. That said, no sibling provides account-level data, so the absence of an explicit alternative pointer is a minor gap rather than a real ambiguity.

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. The description adds the upstream REST mapping, which aids traceability, but says nothing about pagination behavior, the max=1000 cap effect, default sort order, or the shape of returned data. With annotations covering the safety profile, this is adequate but thin.

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 with the functional statement front-loaded and no filler. The REST endpoint sentence is marginal value for an agent but takes almost no space, so the text is efficient overall.

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 list tool with no output schema and no annotations beyond readOnly, the description is the minimum viable: it establishes scope and that filters exist, but leaves return shape, pagination, and result-size behavior for the agent to discover.

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 10 parameters, so the schema already documents each filter including formats and defaults. The description adds no parameter-level meaning beyond what the schema provides, 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 appointments scheduled on the account') and even maps it to the REST endpoint GET /appointments. It is clear what the tool does, though it does not explicitly contrast itself with siblings like acuity_get_appointment (single) or the availability tools.

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 says filters are optional, implying the tool is the broad listing call, but gives no explicit when-to-use guidance, no when-not-to-use, and never names an alternative such as acuity_get_appointment for a single record. The agent must infer routing from the sibling names 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 declares this is a safe read, so the bar is lower. The description adds useful context that deleted/inactive types are excluded by default and maps the call to the underlying REST endpoint (GET /appointment-types), but says nothing about pagination or result size.

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, zero filler; the scope statement is front-loaded and the API mapping is a useful trailing detail.

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 one-parameter read-only list tool with no output schema, the description usefully names the fields returned and the default exclusion of deleted entries. Only pagination/result-shape behavior is unaddressed, which is 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% and includeDeleted is fully documented in the schema, so the description needn't restate it. The mention of 'price, duration and calendars' describes return content rather than parameters, adding little parameter-level 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?

States a specific verb+resource ('List the account's appointment types') and disambiguates what an appointment type is ('services and classes'), plus names the returned fields (price, duration, calendars). It does not explicitly contrast with the similar-sounding sibling acuity_list_appointments, so differentiation is left to the reader.

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?

No when-to-use, when-not-to-use, or prerequisite guidance is given; the only implicit signal is that this is a lookup of catalog/booking data. No alternative sibling (e.g. acuity_list_calendars, acuity_list_appointments) is named or ruled in/out.

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 readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description adds the upstream REST mapping (GET /blocks), which is useful context, but says nothing about pagination, default/maximum result behavior, or whether a date range is needed for meaningful 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?

Two compact sentences, front-loaded with the resource and scope, with the API mapping appended as secondary detail. Nothing is 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 list tool with fully documented parameters and no output schema, the description covers what is returned at a high level. The only real gap is that it does not help the agent choose between listing blocks and querying availability, which the surrounding sibling set makes relevant.

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 max, maxDate, minDate, and calendarID are all documented in the schema itself. The description adds no parameter meaning beyond that, which is the expected baseline when the schema carries the load.

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 ('blocked-off (unavailable) time ranges on the account's calendars'), which is clearly distinct from sibling resources like appointments, clients, or calendars. It does not explicitly name or differentiate itself from the availability tools (acuity_availability_times/dates), but the resource is unambiguous enough for an agent to identify 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 gives no when-to-use guidance, no conditions for selecting this over the availability tools, and no prerequisites. Usage is only implied by the resource name; an agent gets no routing help.

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 with nothing destroyed, so the bar is lower. The description's only added behavioral context is the REST mapping (GET /calendars), which is useful for API-parity and debugging but says nothing about result size, pagination, or whether inactive calendars are included.

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, front-loaded sentences with no filler: the purpose statement comes first and the REST endpoint follows as a compact reference. Every element 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?

For a zero-parameter read tool with readOnlyHint and an empty schema, the definition is essentially sufficient. The only minor gap is that no output schema exists and the description doesn't describe the shape of a returned calendar (id, name), which would help an agent chain into booking 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?

The tool takes zero parameters, so the baseline is 4. There is no parameter behavior the description could add, and the schema is trivially complete; nothing is missing here.

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 account's calendars') and adds a parenthetical that defines what a calendar is in this domain (staff/resources appointments can be booked on), which disambiguates it from siblings like acuity_list_appointment_types or acuity_list_appointments. It does not explicitly name a sibling it should not be confused with, so it stops 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?

The parenthetical 'appointments can be booked on' hints at why an agent would list calendars (to find bookable staff/resource IDs), but there is no explicit when-to-use, when-not-to-use, or alternative named. Usage is only implied from the resource semantics.

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 adds the underlying REST mapping (GET /clients), which is mild useful context, but says nothing about result size, pagination, ordering, or whether the search matches partially or exactly.

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 with the primary purpose front-loaded and the filter qualifier second. No filler, no redundancy, and it is fully readable at a glance.

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 tool with one optional parameter, the core is covered, but with no output schema the description is the only place to learn about result shape, volume, or pagination — and it provides none of that.

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% for the single optional 'search' parameter, so the schema already carries the semantics. The description's '(name/email/phone)' merely restates the field's documented match targets, adding no matching syntax or behavior 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?

The description states a clear verb+resource ('List clients on the account') and scopes it to the account. It does not explicitly name a sibling to contrast with (e.g., acuity_create_client or acuity_get_me), so the differentiation is left implicit, keeping it just 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?

Mentioning the optional search filter implies the usage context (look up matching clients), but there is no explicit when-to-use guidance, no exclusion such as 'to fetch a single client by id use X', and no note about defaults when search is omitted.

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 readOnlyHint annotation already establishes this as a safe read. The description adds useful context beyond that: it discloses the underlying REST endpoint (GET /forms) and that the response includes forms plus their fields. It does not mention pagination, rate limits, or auth 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?

Two short sentences with zero filler. The purpose is front-loaded and the endpoint reference is a compact, useful appendix.

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 tool with no parameters and no output schema, the description covers what it returns ('forms and their fields'), which is the main thing an agent needs. Missing pagination or result-volume notes 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; the schema is empty and coverage is 100%. Baseline 4 applies for a parameterless 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?

States a specific verb and resource ('List the account's custom intake forms and their fields'), which is unambiguous and clearly distinct from sibling list tools like acuity_list_appointments or acuity_list_clients. It does not explicitly name or contrast with any sibling, but the resource scope is self-evident.

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 use this tool versus alternatives, nor any prerequisite or context such as needing an account ID or pagination behavior. For a zero-parameter listing tool the omission is low-risk, but no when-to-use signal is 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 safety is covered. The description adds the underlying REST mapping (GET /labels), which is mildly useful context, but says nothing about return shape, ordering, or whether labels include counts of associated appointments.

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, zero waste, with the core purpose front-loaded before the API detail.

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 trivial zero-parameter read tool with annotations covering the safety profile and no output schema, the description supplies enough to call it correctly. Only the return format is left unspecified, which is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument, account-scoped call.

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 (appointment labels), and the parenthetical 'colored tags' disambiguates labels from the similarly-named sibling acuity_list_appointment_types. It is clear, though it never explicitly names that sibling to route the agent.

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?

No when-to-use, when-not-to-use, or alternative is given. Usage is only inferable from the verb 'List' and the absence of parameters; the description offers no routing guidance among the 17 sibling listing 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=true, so safety is covered structurally. The description adds the REST mapping (GET /orders), which is useful for an agent reasoning about the underlying API, but it says nothing about pagination, default result count, or ordering of results, which matter for a list tool with a 'max' 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?

Two compact sentences with the core purpose front-loaded and no filler. Every clause contributes either scope or the API reference.

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 does not describe the return shape (order fields, pagination, default 'max'). For a read-only two-parameter list tool this is workable but leaves the agent guessing about what comes back and how many results 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 description coverage is 100%, so both parameters ('max' and 'email') are fully documented in the schema and the baseline is 3. The description adds no filtering syntax, date-range hints, or behavior beyond what the schema already states.

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 store orders') and disambiguates what an order is via the parenthetical (product / package / gift-certificate purchases), which separates it from the catalog-oriented acuity_list_products. It does not, however, explicitly contrast itself with the other list_* siblings, 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 statement of when to use this tool versus alternatives such as acuity_list_appointments or acuity_list_products, nor any prerequisites. Usage is only implied by the word 'orders'. No explicit exclusions or routing guidance 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the backend semantics (maps to GET /products) and clarifies the item scope, but nothing about pagination, result size, or auth requirements. It adds modest value over the annotations rather than contradicting them.

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 resource scope and followed by the endpoint mapping. No wasted words, though the REST endpoint note serves developers more than the calling agent.

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-param list tool with no output schema, the description covers what the tool does but says nothing about what the returned list contains or its shape/ordering. Adequate but with a clear gap given no output schema exists to compensate.

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.

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 account's products') and broadens it usefully to cover packages and gift certificates, which an agent would not infer from the name alone. Still, it does not explicitly differentiate itself from the many other acuity_list_* siblings (orders, forms, labels).

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 phrase 'for sale' implies when this list is relevant (catalog/sales context rather than scheduling), but there is no explicit when-to-use, no prerequisites, and no routing to alternatives like acuity_list_orders. 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?

Annotations only supply destructiveHint=true; the description goes further by disclosing real side effects — the calendar is modified and update emails may be sent unless suppressed — plus the underlying PUT endpoint. It omits permission/auth requirements and whether availability is re-validated, so it is strong but not exhaustive.

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, front-loaded with the mutation verb and its side effects, then the API mapping. No filler or repetition; 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 mutation tool with no output schema, the description covers the action, the side effects and the required inputs' intent adequately. It could still note whether admin bypasses availability checks or what happens on a time conflict, but nothing essential to calling it 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 the schema already documents all five parameters including admin, noEmail and calendarID. The description only restates the new-time and optional-new-calendar concepts at a high level, adding no syntax or behavioral detail beyond the schema 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 (reschedules) plus resource (existing appointment) and scope (new time, optionally new calendar), which cleanly separates it from siblings like acuity_cancel_appointment and acuity_create_appointment. The REST endpoint mapping reinforces exactly what operation is performed.

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 makes the usage context unambiguous: this is for moving an already-existing appointment, not creating or cancelling one. It does not explicitly name an alternative tool or state exclusions, but the intent is clear enough that an agent would not confuse it with the cancel or create siblings.

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