Read Appointo bookings, availability and subscriptions; create, reschedule and cancel bookings.
Scored across 10 tools
Each tool maps to a distinct resource+action, and the descriptions actively disambiguate the risky pairs (appointments vs bookings vs products, list_bookings vs list_cancelled_bookings). The write tools (create/cancel/reschedule/update_buffers) are clearly separated by intent.
Every tool uses the same appointo_ prefix followed by a consistent verb_noun snake_case pattern (list_, get_, create_, cancel_, reschedule_, update_). No mixed conventions or vague verbs.
10 tools is well within a sane range for a booking API and each tool covers a real operation (listing the three resource families plus the create/reschedule/cancel/buffer lifecycle). Nothing looks redundant or padded.
The core booking lifecycle is fully covered: check availability, create, list, reschedule, cancel, plus read access to products, appointments and subscription contracts. Gaps remain around editing a booking beyond buffers (e.g. customer details/notes) and any management of subscription contracts beyond listing.
WRITE: cancel a booking, or only some of its customers. The slot is freed and Appointo may notify the customers; whether a Shopify order is refunded is not controlled by this call. Cannot be undone through this server (create a new booking instead). The docs cap this at 100 requests per day. PUT /bookings/cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | Booking id (from appointo_list_bookings). | |
| customer_ids | No | Only cancel these customer ids of the booking; omit to cancel the whole booking. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: states the slot is freed, that Appointo may notify customers, that Shopify refunds are outside this call's control, that it is irreversible through this server, and that the docs cap it at 100 requests/day. These are exactly the side-effect and quota facts an agent needs before invoking a destructive 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?
Four short sentences, each carrying distinct information (mode, scope, side effects, irreversibility, quota, endpoint) with the WRITE marker and scope front-loaded. No filler or repetition.
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?
Covers destructive side effects, quota, and non-idempotent consequences for a tool with no output schema; only the shape of the response (e.g. what the cancelled booking record looks like) is left unstated, which is a minor gap for a cancel operation.
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 booking_id provenance and the customer_ids partial-cancel semantics are already fully documented in the schema. The phrase 'or only some of its customers' mirrors rather than extends the schema, 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?
Opens with an explicit mode marker (WRITE) plus a specific verb and resource: cancel a booking, or a subset of its customers. The full-vs-partial distinction is stated up front and the endpoint (PUT /bookings/cancel) identifies the exact operation, so it is trivially separable from siblings like reschedule_booking or list_cancelled_bookings.
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?
Clearly says this cannot be undone and directs the agent to create a new booking instead, which is a genuine when-not/alternative statement. It does not explicitly compare against appointo_reschedule_booking or note the preconditions for a partial customer cancel, so it falls just short of a full routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a booking for a customer on an appointment (bookable service) at a time slot. This is a real booking: Appointo may email the customer a confirmation and reserve the slot; the booking can later be cancelled with appointo_cancel_booking. Check appointo_get_availability first. Not idempotent: calling twice creates two bookings. The docs cap this at 100 requests per day. POST /bookings.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Customer name. | |
| Yes | Customer email. | ||
| phone | No | Customer phone number. | |
| quantity | No | Number of spots (default 1). | |
| timestring | Yes | Start of the time slot, ISO 8601, e.g. 2026-11-03T14:00:00-05:00 (use a date only, 2026-11-03, for a day booking). Check appointo_get_availability for real slots. | |
| appointment_id | Yes | Appointo appointment id (from appointo_list_appointments). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces rather than contradicts that. It adds genuinely new context the annotations cannot carry: Appointo may email the customer and reserve the slot, plus a 100-requests-per-day cap. It stops short of describing failure behavior (e.g. what happens if the slot is taken), which keeps it at 4.
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 operation class and core action, followed by side effects, preconditions, and limits in descending order of importance. Every sentence carries a distinct fact; even the trailing rate limit and POST route are non-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 mutation tool with no output schema, the description covers side effects, irreversibility/idempotency, quota, and prerequisites. The main omission is error behavior when the slot is unavailable or the customer lacks a valid email, which an agent would benefit from knowing before calling.
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 (including timestring's ISO 8601 format and the appointment_id source) is already documented in the schema. The description adds only the availability-check pointer for the time slot, which is the baseline expectation when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (create a booking) plus the exact scope: a customer, an appointment (bookable service), and a time slot. The 'WRITE:' prefix and the explicit contrast with appointo_cancel_booking make it distinguishable from every sibling at a glance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition ('Check appointo_get_availability first') and names the follow-up tool (appointo_cancel_booking) that reverses this action. An agent knows both the ordering constraint and the undo path without consulting anything else.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The free time slots of one appointment (bookable service) from start_date, optionally to end_date. Use it before creating or rescheduling a booking. GET /appointments/{appointment_id}/calendar_availability.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | Last day, yyyy-mm-dd. | |
| start_date | Yes | First day, yyyy-mm-dd. | |
| appointment_id | Yes | Appointo appointment id (from appointo_list_appointments). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results are *free/available* slots rather than all slots and that it precedes a write, which is useful context. It says nothing about timezone handling, result caps, or pagination, so it stays at minimum-viable-plus.
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: purpose first, then usage guidance. The trailing endpoint path is borderline redundant but scannable and doesn't obscure the key facts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries some burden for describing the return value; it says 'free time slots' but not their structure or whether an empty list means fully booked. For a simple 3-parameter read tool the description is adequate but leaves that 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 coverage is 100% and each parameter is already documented (including the appointment_id provenance hint to appointo_list_appointments). The description adds only the range framing — start_date as anchor and end_date as optional — which is marginal 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 resource (free time slots of a single appointment/service) and its date scope, plus the underlying GET endpoint. An agent can distinguish it from list_appointments or list_bookings, though 'free time slots' is a noun phrase rather than an explicit verb.
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?
'Use it before creating or rescheduling a booking' gives concrete ordering guidance that ties directly to the appointo_create_booking and appointo_reschedule_booking siblings. No explicit when-not/exclusion is stated, but the prerequisite context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List appointments, i.e. the bookable services/variants, with name, price, currency and configuration. Filter by product or fetch one by id. These are the services customers book, not the bookings themselves (use appointo_list_bookings for those). GET /appointments.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page, 1-100 (default 25). | |
| offset | No | Number of results to skip (default 0). Pass the previous reply's next_offset. | |
| product_id | No | Only appointments of this Appointo product id (the `id` from appointo_list_products). | |
| search_term | No | ||
| appointment_id | No | Fetch a single appointment by id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds what fields come back (name, price, currency, configuration) and the underlying GET endpoint. It does not discuss pagination behavior (limit/offset + next_offset) or rate limits, which would have made it 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?
Front-loads the identity and disambiguation in the first sentence, then adds the retrieval fields and modes, ending with the endpoint. Every sentence carries unique information and there is 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?
There is no output schema, and the description compensates by naming the returned fields (name, price, currency, configuration) plus the endpoint. The only gap is the undocumented search_term parameter and any note on paging behavior, which the schema partially covers via next_offset.
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 80% and the schema already documents limit, offset, product_id and appointment_id in detail. The description only restates the product-filter and single-fetch modes and says nothing about the undocumented search_term parameter, so it adds little beyond the schema. 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?
Names a specific verb and resource ('List appointments') and immediately disambiguates the overloaded term by defining appointments as bookable services/variants, while naming what they are not. The agent can distinguish it from appointo_list_bookings without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the exclusion ('not the bookings themselves') and routes to appointo_list_bookings for those, and describes the two access modes: filter by product, or fetch one by id. Alternatives are named with the condition that selects them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List bookings with time, product, duration, quantity, price and the customers (name, email, phone, address). Filter upcoming/past or search; pass booking_id for one booking. The customers' cancel/reschedule link ids are never returned. GET /bookings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page, 1-100 (default 25). | |
| offset | No | Number of results to skip (default 0). Pass the previous reply's next_offset. | |
| status | No | Only upcoming or only past bookings. | |
| booking_id | No | Fetch a single booking by id. | |
| search_term | No | Searches product name, customer name, email, phone and order name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description isn't burdened with safety disclosure. It still adds real value by stating a privacy behavior the annotations cannot convey: customer cancel/reschedule link ids are never returned, and it pins the underlying endpoint (GET /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?
Three short sentences, front-loaded with purpose and output fields, followed by filtering guidance and one behavioral caveat. No filler or restated 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?
With no output schema, the description properly carries the return-shape burden by naming the fields and the excluded link ids; pagination is adequately covered by the offset/next_offset schema text. Minor gaps remain on default ordering and whether cancelled bookings appear in this 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% and every parameter is documented in-schema, so the baseline is 3. The description restates the filter/search/single-id behaviors without adding syntax, defaults, or interaction rules (e.g., whether search_term is ignored when booking_id is set).
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 bookings") and enumerates the returned fields (time, product, duration, quantity, price, customer contact details), so the agent knows exactly what this returns. It does not, however, distinguish itself from close siblings like appointo_list_cancelled_bookings or appointo_list_appointments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Filter upcoming/past or search; pass booking_id for one booking" gives clear in-tool usage modes, but those modes are already implied by the schema's status/search_term/booking_id params. There is no guidance on when to pick this over list_appointments, list_cancelled_bookings, or list_subscription_contracts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cancelled bookings, same shape as appointo_list_bookings. GET /bookings/cancelled_bookings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page, 1-100 (default 25). | |
| offset | No | Number of results to skip (default 0). Pass the previous reply's next_offset. | |
| status | No | Only upcoming or only past bookings. | |
| search_term | No | Searches product name, customer name, email, phone and order name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint path and shape parity, saying nothing about pagination behavior beyond what the schema already documents or about result ordering.
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, the identifying information first and the shape-parity hint second. 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 paginated list tool with a fully documented schema and no output schema, the definition covers purpose and return shape by reference to appointo_list_bookings. Only ordering and pagination-flow hints are missing, and offset's own description carries the next_offset guidance.
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, status and search_term are each documented in-schema, and the description adds no parameter detail on top. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource (list cancelled bookings) with the underlying endpoint, and it distinguishes itself from appointo_list_bookings by scoping to cancelled records while noting the identical response shape. A sibling-usage sentence naming appointo_list_bookings explicitly would push this to 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?
'Same shape as appointo_list_bookings' implies the tool is the cancelled-only variant of that list call, but it never states when to prefer one over the other or any exclusion. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Shopify products that are set up as bookable in Appointo: name, appointment type, whether the widget is shown, and each product's appointments (the bookable variants/services with price, currency and id). Use an appointment id for availability and bookings. GET /products.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page, 1-100 (default 25). | |
| offset | No | Number of results to skip (default 0). Pass the previous reply's next_offset. | |
| search_term | No | Filter by product name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: the exact response shape (per-product appointments with price, currency and id) and the underlying endpoint 'GET /products'. No rate-limit or pagination-behavior detail is given, which is the only remaining gap.
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 first describes the resource and return contents, the second the follow-up usage, then the endpoint. Information is front-loaded and the parentheticals are dense but purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by enumerating the returned fields at two levels (product and nested appointment). With all three parameters documented in the schema and the paging convention referenced, an agent has everything needed to call and consume this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, offset, search_term) are fully documented in the schema at 100% coverage, including defaults and next_offset paging guidance, so the baseline is 3. The description adds nothing about them — no note about search_term matching semantics or the 100-result cap.
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 Shopify products that are set up as bookable in Appointo') and enumerates the fields returned (name, appointment type, widget visibility, nested appointments with price/currency/id). The resource (products) is clearly distinct from the appointment- and booking-centric siblings, so an agent can pick it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use an appointment id for availability and bookings' routes the agent to the follow-up tools (appointo_get_availability, appointo_create_booking) after this discovery call, giving clear usage context. It does not name when *not* to use this tool or compare it to an alternative product-listing path, so it falls 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.
List the recurring booking subscription contracts (customers who subscribed to repeat appointments). Search by product, variant, order number or customer name. The API documents no paging for this list. GET /appointment_subscriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| search_term | No | Product name, variant name, order number or customer name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and non-destructive, so the description's main contribution is the explicit note that the API documents no paging for this list — a genuine behavioral constraint an agent would otherwise assume away. It does not describe result size, sorting, or the shape of returned contracts.
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 resource definition, then the search surface, then the paging caveat. 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 single-parameter read-only list tool with no output schema, the description covers purpose, filtering, and the notable absence of paging. Missing only what the returned contract objects contain and whether search is a partial or exact match.
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 parameter already enumerates product name, variant name, order number and customer name. The description restates that same list verbatim, adding no format hints, matching behavior, or empty-string handling 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 the recurring booking subscription contracts') and clarifies the domain with the parenthetical about repeat-appointment subscribers, which separates it from appointo_list_bookings and appointo_list_appointments. It does not explicitly name or contrast those siblings, 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 search-fields sentence implies how to narrow results, but there is no statement of when to choose this tool over the booking/appointment list siblings, nor any exclusion or prerequisite. Usage is inferable rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: move a booking (or only some of its customers) to a new time slot. Appointo may notify the customers of the change. override=true forces the booking into the slot even if it is unavailable or full, so leave it off unless the user explicitly asked for it. The docs cap this at 100 requests per day. PUT /bookings/reschedule.
| Name | Required | Description | Default |
|---|---|---|---|
| override | No | Force the slot even if unavailable (default false). | |
| booking_id | Yes | Booking id (from appointo_list_bookings). | |
| timestring | Yes | Start of the time slot, ISO 8601, e.g. 2026-11-03T14:00:00-05:00 (use a date only, 2026-11-03, for a day booking). Check appointo_get_availability for real slots. | |
| customer_ids | No | Only move these customer ids of the booking; omit to move the whole booking. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive=true, idempotent=true and openWorld=true, so the safety profile is covered; the description adds real value on top with the customer-notification side effect, the documented 100-requests-per-day cap, and the meaning of forcing a booking into a full slot. It omits what happens when the target slot conflicts for other bookings or what the response contains.
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 a 'WRITE:' marker, then purpose, then side effects, then parameter caution, then limit. Five short clauses with no filler; even the trailing 'PUT /bookings/reschedule' is a cheap confirmation of the mutation.
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 destructive mutation with no output schema, the description covers purpose, notification behaviour, rate limit and the danger parameter, which is most of what an agent needs. It could still say whether a reschedule invalidates the old slot immediately or what is returned on success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents all four parameters with formats and provenance, so the baseline is 3. The description adds intent-level meaning beyond the schema's mechanical 'Force the slot even if unavailable' by framing override as an escalation that requires explicit user consent.
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 (move/reschedule) plus the resource (a booking or a subset of its customers) and the destination (a new time slot). This is clearly distinct from the sibling write tools appointo_create_booking, appointo_cancel_booking and appointo_update_booking_buffers without needing to open any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit conditional rule for the risky path: 'override=true... leave it off unless the user explicitly asked for it', which tells the agent when NOT to use a capability. It does not discuss the obvious alternative of cancelling and re-creating, so it stops short of naming an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: set the start and/or end buffer time (minutes blocked before/after) of one booking. At least one value is required. The docs cap this at 100 requests per day. PUT /bookings/{booking_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | Booking id (from appointo_list_bookings). | |
| end_buffer_time | No | Buffer after the booking, minutes (> 0). | |
| start_buffer_time | No | Buffer before the booking, minutes (> 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a non-read-only, destructive, idempotent, open-world write. The description adds useful behavioral context beyond the annotations, including the WRITE label, the 100 requests/day documentation cap, the PUT endpoint, and the requirement to supply at least one value. It does not elaborate on exactly how existing buffer values are affected when only one is provided, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the WRITE label and core action. Every sentence adds useful information: the operation, the at-least-one-value constraint, the rate limit, and the 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 mutation tool with complete schema descriptions and annotations covering safety and idempotency, the description supplies the key operational facts an agent needs. A minor gap is that it does not state whether an omitted start or end buffer is left unchanged or cleared.
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. The description adds meaningful semantics beyond the schema by clarifying that buffers represent minutes blocked before/after the booking and by imposing the cross-parameter rule that at least one of start_buffer_time or end_buffer_time must be supplied.
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: setting start and/or end buffer times for one booking. It clarifies the units and meaning of the buffers as minutes blocked before/after, which is more precise than the title alone.
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 clearly establishes the usage constraint that at least one buffer value is required. It does not explicitly compare against sibling tools, but no sibling appears to perform the same buffer-update operation, so the usage context is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
appointo_cancel_bookingappointo_create_bookingappointo_get_availabilityappointo_list_appointmentsappointo_list_bookingsappointo_list_cancelled_bookingsappointo_list_productsappointo_list_subscription_contractsappointo_reschedule_bookingappointo_update_booking_buffersRead appointments, types, calendars and availability; create, cancel or reschedule bookings.
Read AgendaPro bookings, slots, clients, services and sales; create, update and cancel bookings.
Manage YouCanBook.me bookings, booking pages, appointment types, team members and locations.
Read splose patients, appointments, invoices, cases; book and cancel appointments, record payments.
Add one secure layer between your agents and this server.
