Bookeo MCP by usefulapi

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

Annotations only declare destructiveHint=true; the description goes well beyond that by clarifying the cancellation is a soft delete (booking persists, visible via includeCanceled) while seats are freed, and that no cancellation fee is charged. This nuance materially changes how an agent should reason about a "destructive" tool, which is exactly the kind of context annotations cannot 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?

Three tight sentences front-loaded with the action, with no filler; each adds a distinct fact (soft delete, seat release, no fee). The includeCanceled reference is a slight tangent since it is not a parameter of this tool, but overall it is efficient.

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

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

With no output schema, the description carries the burden of explaining effects and does so for the core outcomes (persistence, seat release, fee behavior). Notification and recurring-series behavior are covered in the schema parameter descriptions, so the remaining gaps are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters (reason, notifyUsers, notifyCustomer, cancelRemainingSeries, trackInCustomerHistory, bookingNumber) are already documented in the schema. The description adds no parameter-level syntax or semantics 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 and resource ("Cancel a booking") and even names the underlying API call (DELETE /bookings/{bookingNumber}), so the operation is unambiguous. It does not explicitly contrast with nearby siblings like bookeo_update_booking or bookeo_get_booking, which is the only thing keeping it from 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 description explains what cancellation does but never says when to choose it over alternatives (e.g., update_booking for modifications, or a fee-applying path). The note that the cancellation policy is NOT applied hints at a use-case distinction but stops short of naming any alternative or exclusion condition.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the behavioral burden and delivers real value: 'Does NOT record any payment' and 'Reversible with bookeo_cancel_booking' tell the agent about side effects the annotation cannot express. The statement that a hold is released on success is also useful. It does not mention permission requirements or rate limits, and the 'reversible' claim sits somewhat uneasily beside destructiveHint=true, though it is clarifying rather than contradictory.

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 dense sentences, front-loaded with the core action and customer choice, then constraints, then side effects. No filler, though the sentences are tightly packed and the product-type rules could be slightly more scannable.

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 18-parameter nested-object mutation with no output schema, the description covers the critical decision points (which customer field, which scheduling field per product type, hold conversion, no payment, reversibility). It omits what the call returns (e.g. the new booking id) and any confirmation/notification defaults, which an agent would benefit from knowing given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds cross-parameter conditional logic the schema cannot express: product-type-dependent eventId/startTime requirements and hold conversion via previousHoldId. Many of the 18 parameters (options, resources, notify flags, promotionCodeInput, mode, externalRef) receive no description-level treatment, but the schema covers them individually.

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 confirmed booking') plus the two mutually exclusive customer paths (existing customerId vs new customer object). It also distinguishes itself from adjacent tools by naming the availability tools, bookeo_create_hold and bookeo_cancel_booking, so an agent can place it in the workflow without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditional routing: fixed/fixedCourse products need an eventId from the availability tools, flexibleTime products take eventId or startTime, and previousHoldId converts an existing hold. It names the related tools but never states an explicit when-not-to-use condition or a fallback if the slot is unavailable, so it stops short of full 5-level guidance.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered structurally. The description adds little behavioral context beyond the endpoint mapping — it does not say whether duplicate customers are rejected, whether an existing customer is matched/merged, or what identifier comes back. It does not contradict 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?

Three terse clauses, each carrying distinct information (what it does, when it is unnecessary, and the endpoint). Front-loaded with the action and free of 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?

No output schema exists, so the description should ideally say something about the created record or its identifier, and it stays silent. It handles the routing question well but leaves a 10-parameter, nested-object create call thinly documented.

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 only 20% across 10 parameters (including nested phoneNumbers and streetAddress objects) and the description supplies no field-level meaning at all. With low coverage, the description was expected to compensate with format or required-field guidance, and it does not.

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 customer record') and adds the REST mapping (POST /customers). It also clarifies its boundary against sibling create flows, but does not distinguish it from the related bookeo_get_customer / bookeo_update_customer beyond the obvious 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?

Explicitly tells the agent this step is NOT required before booking because bookeo_create_booking can create the customer inline — a genuine when-not-to-use rule with the alternative named. It does not state the positive case where you specifically do want a standalone customer, so it is not quite 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?

With only destructiveHint=true in annotations, the description carries most of the burden and delivers real value: default/max hold duration, automatic expiry, and the fact that it returns final price/taxes/amount payable. It omits edge behavior such as what happens when a hold is superseded or expires before booking, but the core behavioral facts are disclosed and do not conflict with destructiveHint.

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 tight sentences, front-loaded with the reservation action and price-check payoff, followed by the integration hint and expiry note. The trailing 'Bookeo: POST /holds' is a compact endpoint marker; 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 14-parameter tool with nested objects and no output schema, the description usefully covers what is returned (final price, taxes, amount payable) and how the hold feeds into booking creation. It stops short of covering failure modes or expiry-to-booking timing, which a complex mutation tool would ideally address.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 14 parameters is already documented, including holdDurationSeconds defaults and the previousHoldId meaning. The description mostly restates duration limits and the hold-id linkage rather than adding 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+resource (temporarily reserve seats/resources for a draft booking) and the outcome (final price, taxes, amount payable). It clearly distinguishes itself from bookeo_create_booking, which is the sibling it feeds into.

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 itself as 'the recommended step before bookeo_create_booking' and explains the handoff (pass the returned hold id as previousHoldId). It also states holds expire automatically, so the agent knows the hold is transient scaffolding rather than a substitute for a real booking.

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 signals a safe read, but the description goes further by disclosing the payload shape (account identity plus granted permission scopes such as bookings_rw_all) and framing the call as low-cost. It does not mention auth prerequisites or rate limits, which would be the remaining useful additions.

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, each carrying distinct information: what is returned, why to call it, and the underlying endpoint. The return value is front-loaded and nothing is 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?

With no output schema, the description must convey the return contents, and it does so via concrete scope examples. Auth and cost are addressed implicitly. Complete enough to call correctly, though it could say more about the account object's fields.

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 and there is nothing for the description to disambiguate. It correctly adds no parameter commentary, which would be noise 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+resource: showing which account the credentials map to and which permission scopes were granted. This is unmistakably distinct from every sibling, all of which operate on bookings, customers, payments or products. It stops short of explicitly differentiating itself by name, but no sibling is close enough to warrant 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?

"A cheap way to confirm the setup works" gives a concrete use case (credential/setup validation, likely as a first call before other operations). It offers no exclusions or alternatives, but none exist in this sibling set. Clear context without explicit when-not guidance.

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

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

readOnlyHint=true already establishes the safety profile, so the description only needs supplementary context, and it delivers: the hard 31-day window cap, the product-type constraint, and the underlying Bookeo endpoint (GET /availability/slots). It stops short of describing result ordering or pagination semantics, which the schema partially covers via pageNavigationToken, so a 4 rather than 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?

Three short sentences, zero filler: capability and scope first, the exclusion/alternative second, the API mapping last. Every sentence carries decision-relevant information and the key routing signal ('not for flexibleTime') is not 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?

With no output schema, the description compensates by naming the returned fields, and it covers the domain constraint (31-day cap), the supported product types, and the sibling routing. An agent has everything needed to select and call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all seven parameters including the subtle 'mode=backend' manager override and the -00:00 timezone convention are already documented in the schema. The description adds no parameter-level meaning beyond the field names it lists as outputs, so the baseline 3 applies.

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

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

The description pairs a specific verb ('List available slots') with the resource, its scope ('fixed and fixedCourse products'), the window constraint, and even the returned fields (eventId, start/end, seats available). It explicitly excludes flexibleTime products and names the sibling to use instead, so the tool is distinguishable from bookeo_search_matching_slots without any schema inspection.

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?

States the positive use case (fixed/fixedCourse products in a window up to 31 days) and the explicit exclusion with a named alternative: 'Not for flexibleTime products — use bookeo_search_matching_slots for those.' This is the when/when-not/alternative pattern at full strength.

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 is a safe read, so the bar is lower, yet the description adds real value by enumerating the returned fields (product, times, participants, options, price, paid amount, status) and the status enum values. It does not mention auth or pagination, but for a single-item read that gap is minor.

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 clauses, front-loaded with the core purpose followed by the returned fields, plus a terse API endpoint reference. Nothing is padded and 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?

No output schema exists, so the description bears the return-value burden and largely meets it by listing the key returned fields and status values. The remaining gap is that the two expand flags and their effect on the response are never mentioned.

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 documents all three parameters, so the baseline is 3. The description only echoes the bookingNumber input and says nothing about expandCustomer/expandParticipants, 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 ('Get one booking by its booking number') and enumerates the payload it returns. The phrase 'one booking' cleanly distinguishes it from the sibling bookeo_list_bookings, so an agent can route 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?

Usage is implied by 'by its booking number' (you must already have the number), but there is no explicit when-to-use versus when-not, and no named alternative such as list_bookings or search_matching_slots. Adequate but leaves the routing inference to the agent.

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 field list and the underlying endpoint (GET /settings/business), which is modest extra context, but it says nothing about auth requirements, scope, or return format beyond the field names.

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 that are front-loaded with the payload description and footnote the API path. No wasted wording.

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 parameters and no output schema, the description carries the burden of describing the return, and it does so by enumerating the fields. It stops short of explaining response structure or nesting, but for a zero-arg singleton getter this is largely adequate.

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 per the rubric the baseline is 4. There is nothing for the description to clarify at the parameter level.

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 (the business) and enumerates the fields returned (name, contact details, address, website, description). The resource is unique among siblings, all of which target bookings, customers, payments, or slots, so the agent can distinguish it 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 rather than stated: it's the only business-settings getter, so there is no real alternative to route against. It gives no explicit when-to-use framing, but the singleton nature of the tool means little guidance is needed.

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 the safe read profile, and the description goes further by disclosing exactly what data the call returns (contact details, next/previous booking, cancellation and no-show counts, membership, store credit). It also cites the underlying Bookeo endpoint, adding useful behavioral context. It does not discuss error behavior for missing ids or whether the read is cached.

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 with zero filler: the return contents come first, the API reference last. The scope verb leads the sentence, so the agent reads the essential information 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?

With no output schema, the description appropriately compensates by listing the returned fields, and a single required parameter keeps the surface simple. Missing only exclusions against sibling tools for a fully complete picture.

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?

Only one parameter ('id') exists and the schema already describes it at 100% coverage ('The customer id.'). The description adds no format, prefix, or lookup semantics 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?

States a specific verb and resource ('Get one customer') and enumerates the payload contents (contact details, bookings, cancellations/no-shows, membership, store credit). The word 'one' implicitly contrasts with the list_customers sibling, though it never names the alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: retrieving a single customer by id versus the sibling list_customers or list_customer_bookings. There is no explicit when-to-use guidance or stated prerequisites for choosing this tool over its siblings.

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 goes beyond that by enumerating the concrete fields returned (amount, method, reason, received time, customer, gateway transaction id), which is genuinely useful since there is no output schema. It stops short of noting error behavior for an unknown id.

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 listing the payload, followed by a short endpoint reference. No filler, 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?

For a single-record read tool with readOnlyHint and no output schema, the description supplies the return fields an agent needs to decide whether to call it. Only the failure mode for a nonexistent id is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage ('The payment id.'), so the schema already carries the semantics. The description adds nothing about id format or provenance, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Get one payment') and enumerates the fields returned, so the agent knows exactly what it retrieves. The word 'one' implicitly separates it from the sibling list tools (bookeo_list_payments, bookeo_list_booking_payments), though that contrast is never made explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: retrieving a single payment by id suggests you already know the id. The description never states when to prefer this over bookeo_list_payments or bookeo_list_booking_payments, nor any precondition for having a valid id.

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 the safe-read profile, and the description adds genuinely non-obvious response semantics: refunds are returned as negative amounts. That is a behavioral detail no annotation or schema conveys. It stops short of mentioning pagination behavior even though two pagination parameters exist.

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 filler: the operation and its one non-obvious return convention come first, followed by the endpoint reference. Nothing is padded.

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

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

For a simple read tool with a fully documented schema, the description covers what is returned (payments plus negative refunds) and the target scope. No output schema exists, yet the response shape is described at an adequate level; the only omitted behavior is pagination workflow, which the schema already explains.

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 are self-documenting (including the pagination token mechanics). The description only confirms that bookingNumber selects the target booking and adds nothing about pageNumber/itemsPerPage. 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 ('payments ... received for one booking'), with the scoping phrase 'for one booking' that separates it functionally from the sibling bookeo_list_payments (all payments). It does not name that sibling explicitly, so the differentiation is inferable 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 phrase 'for one booking' implies the use case (you already have a bookingNumber and want its payment history), but there is no explicit guidance on when to prefer this over bookeo_list_payments or bookeo_get_payment, nor any stated 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?

Annotations already establish readOnlyHint=true, and the description adds real behavioral constraints beyond that: the mandatory time-pair rule, the 31-day cap, and the fact that canceled bookings are excluded unless requested. It stops short of describing pagination behavior or response shape, but the safety profile is already covered by 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 dense opening sentence front-loads the required constraint and filters, followed by a short API pointer. There is no filler or repetition of schema details.

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 11 parameters, the description covers the essential call semantics: the mandatory time-pair rule, the 31-day limit, optional filters, and expansion flags. Return format and pagination behavior are left to the schema's pageNavigationToken description, which is acceptable but not fully closed.

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 contributes a rule the schema never states: that at least one of the two time-parameter pairs is mandatory, and how startTime/endTime relate to lastUpdatedStartTime/lastUpdatedEndTime. It also confirms productId/canceled/expand act as optional filters.

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

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

The description states a specific verb and resource ('List bookings') and immediately scopes it by the two supported query modes (start time pair and/or last-change pair), plus the optional filters. That is enough to separate it from single-booking siblings like bookeo_get_booking and from the more narrowly scoped bookeo_list_customer_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?

It gives concrete preconditions: at least one time pair is required and each pair may span at most 31 days. It does not, however, name an alternative tool or say when to prefer bookeo_get_booking or bookeo_list_customer_bookings over this list call, so usage context is clear but not fully routed.

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=true annotation already declares this a safe read, so the description carries a lower burden. It adds the underlying endpoint (GET /customers/{id}/bookings) and the optional date scoping, but says nothing about pagination behavior or result volume beyond what the schema's pageNavigationToken parameter already implies.

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 no filler, and the primary scope (one customer's bookings) is front-loaded. The trailing REST endpoint reference is compact and useful for agents mapping to the Bookeo API.

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 only 7 params, full schema coverage, and a readOnly annotation covering the safety profile, the description supplies what is needed to invoke the tool. The absence of return-shape or pagination narrative is a minor gap given the richly documented schema, and no output schema exists to offset 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 every parameter (dates, paging, expandParticipants) is already documented. The description only reiterates optional date filtering and adds no syntax or format detail beyond the schema, making the baseline 3 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?

The description states a specific verb (List) and resource (one customer's bookings), scoping it to a single customer with an optional date range. This implicitly separates it from the sibling bookeo_list_bookings, but it never names that sibling explicitly, so the differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no mention of alternatives. The phrase 'one customer's bookings' hints that the tool is customer-scoped rather than business-wide, but the agent must infer that bookeo_list_bookings covers the other case.

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=true annotation already establishes this is a safe read, so the description's 'Bookeo: GET /customers' mainly confirms it. It adds the optional-filter semantics but says nothing about pagination flow, default page size, or result ordering beyond what the schema already declares.

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 dense sentence front-loads the core action and folds filters and the underlying endpoint into one pass with no filler. Nothing in it is redundant padding.

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 eight-parameter listing tool with no output schema, the coverage is solid: the description signals the searchable fields and the member/date filters, and the schema handles pagination tokens and defaults. Only the shape of the returned customer list and pagination expectations are left implicit.

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 eight parameters (pageNumber, searchText, searchField, createdSince, itemsPerPage, currentMembers, currentNonMembers, pageNavigationToken) are already documented in the schema. The description restates the search fields and member filters without adding format, default, or interaction details.

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/search) and resource (customers) and enumerates the filter dimensions, so an agent can tell it apart from bookeo_get_customer or bookeo_create_customer. It stops short of naming the sibling list/get tools explicitly, but the scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('search ... by name, firstName, lastName or emailAddress ... optionally only members/non-members or created since a date') but never states when to prefer it over bookeo_get_customer for a single customer or bookeo_list_customer_bookings. No exclusions or prerequisites are given, so the routing is left to inference.

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, and the description adds a genuinely useful non-obvious behavior: refunds appear as negative amounts. It still omits pagination/rate-limit behavior, but the refund convention is real added value beyond 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 short clauses, front-loaded with scope, then the refund convention, then the underlying endpoint. No filler and nothing redundant with the schema.

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 full schema coverage and no output schema, the description covers scope, filtering, and refund sign semantics. Minor gaps remain (default ordering, whether paymentMethodOther is passed through), but nothing essential for correct invocation 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 seven parameters in detail (RFC 3339 format, enum, pagination). The description only restates the time-period and payment-method filters, adding no syntax or semantics 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 and resource ('List payments received in a time period') plus optional scoping, which clearly separates it from a single-payment fetch. It does not, however, name or distinguish itself from close siblings like bookeo_get_payment or bookeo_list_booking_payments.

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 'optionally by payment method' clause implies when the tool is useful, but there is no explicit when-to-use guidance and no mention of the alternative siblings (get_payment for one payment, list_booking_payments for a booking's payments) that an agent must choose between.

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 is a safe read, so the description's marginal contribution is modest. It does add what the response contains (ids, seats taken) and the underlying endpoint (GET /settings/peoplecategories), which is useful but not deep behavioral disclosure such as 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 tight sentences with no filler; the purpose and return contents lead, and the endpoint reference is compactly appended. 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?

With no output schema, the description carries the burden of describing returns, and it does so (category names, ids, seats taken) plus the API path. It is nearly complete; only edge details like ordering or pagination are absent, which are minor for a small account-level settings 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 the baseline is 4. The description correctly implies an account-wide listing with no filtering inputs, consistent with the empty 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 participant categories the account uses') and enriches it with concrete examples (default Adults/Children/Infants, custom like Students). No sibling tool lists participant categories, so it is unambiguous against the other list_* 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?

'Needed for peopleNumbers' gives a concrete downstream condition that tells the agent when to reach for this tool rather than guessing. It does not name alternative tools or exclude any cases, but the when-to-use context is clear and actionable.

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 the safe-read profile, and the description adds genuinely useful context beyond it: the exact shape of what comes back (ids, type, duration, participant limits per people category, default rates, options) and the underlying endpoint GET /settings/products. With no output schema present, this return-content detail is the main source of behavioral information.

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, front-loaded with the purpose and outcome, followed by a compact API reference. No filler, no repetition of schema details, and nothing that could be trimmed without losing information.

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

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

With five optional parameters, no output schema, and a read-only annotation, the description supplies the response contents and the endpoint, which is most of what an agent needs. It stops short of explaining pagination flow, but the schema's pageNavigationToken description already covers 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%, so every parameter (lang, type, pageNumber, itemsPerPage, pageNavigationToken) is already fully documented in the schema. The description only restates the type enum inline, adding no semantics beyond what structured data provides; 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 (bookable products) and disambiguates the resource by enumerating what counts as a product: tours, classes, courses, appointments. The type enumeration (fixed, fixedCourse, flexibleTime) further pins down the domain, and it is clearly distinct from siblings like bookeo_list_resources or bookeo_list_people_categories.

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 — you call this to retrieve the product catalog — but there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as availability or slot search tools. It never says, for example, that this must be called before creating a booking to obtain a product id.

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 useful structural fact that the response is a two-level hierarchy of resource types containing resources, plus the underlying endpoint (GET /settings/resources). It says nothing about pagination behavior or result volume, which the schema partially covers.

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 the API endpoint as a compact trailing reference. No filler, no repetition 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 simple paginated read tool with readOnlyHint and a fully documented schema, this covers what the tool returns and how it maps to the API. Only minor gaps remain, such as whether pagination is likely needed or how many resource types typically exist.

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 pageNumber, itemsPerPage, and pageNavigationToken are already fully documented with ranges and usage notes. The description adds no parameter meaning beyond that, making the baseline 3 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?

States a specific verb+resource: listing resource types and their constituent resources (guides, instructors, rooms, boats) with ids. The examples make the domain concrete and distinguish it from sibling list tools like bookeo_list_people_categories or bookeo_list_products. It stops short of explicitly contrasting with those siblings, but the resource is clearly named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no conditions, and no mention of the sibling list tools an agent might confuse this with (people categories, products). The implied usage of a list endpoint is inferable, but the description offers 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 is already declared, yet the description still adds non-obvious behavior: pagination ignores all other fields on subsequent calls, the search window is capped at 31 days, results include an estimated price, and flexibleTime products are covered. It stops short of describing response shape or failure modes, but it goes beyond the annotations meaningfully.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then constraints, then paging, then read-only, then endpoint mapping — every sentence carries information for an agent. The trailing Bookeo endpoint line is somewhat procedural but useful for traceability, and the density never becomes padding.

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, no-output-schema read tool, it covers scope, window limits, paging continuation and the price signal. The main remaining gap is what a result row contains (slot structure, availability count), which the agent must discover at runtime, but nothing needed to call the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including mode, options, resources and peopleNumbers is already documented in the schema. The description echoes the key inputs (participant counts per category, options, resources) and adds paging semantics that largely duplicate the pageNavigationToken schema text; 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 slots that can take a given party') with the matching criteria enumerated and the return payoff ('with an estimated price'). It implicitly separates itself from bookeo_get_availability_slots via the party-matching framing and 'works for all product types, including flexibleTime', but never names that sibling explicitly, so the differentiation is inferred 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?

Gives real operating context: the 31-day window cap and the paging rule ('to page through results pass only pageNavigationToken (+ pageNumber)'), which directly tells an agent how to continue a search. It does not state when to prefer this over bookeo_get_availability_slots or bookeo_create_hold, so the alternative selection is left implicit.

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; the description adds genuinely useful implementation context — that it internally GETs the current booking and PUTs the full booking back with only your changes applied. This read-modify-write semantics is exactly what prevents an agent from assuming partial-field PUTs and clobbering data. It stops short of stating permission requirements or what happens to fields left unspecified.

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, front-loaded with the verb and the mutable surface, followed by the one behavioral detail that matters (merge semantics). No filler or restatement of the name.

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 tool with no output schema and only a destructiveHint annotation, the description supplies the essential mental model (merge-then-PUT, reschedule alternatives). Minor gaps remain around notifyUsers/notifyCustomer defaults and error/irreversibility behavior, but nothing that would cause a misinvocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 83%, so the baseline is 3, but the description adds real meaning: it groups eventId vs startTime/endTime as the two alternative reschedule routes and frames peopleNumbers/options/resources as replacement-style changes. This routing information is not derivable from the flat 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 ('Change an existing booking') plus the categories of change (reschedule, participant counts, options, resources, external reference), and the reschedule routes are named explicitly. An agent can distinguish this from bookeo_create_booking and bookeo_cancel_booking 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?

The description implies the context (modifying an existing booking, reschedule via eventId or startTime/endTime) but never states when to use this versus siblings like bookeo_create_hold or bookeo_cancel_booking, nor any preconditions such as needing the booking to be in a mutable state. Usage is inferable but not spelled 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?

Annotations only supply destructiveHint=true; the description adds a genuinely non-obvious behavioral trait — that it performs a read-modify-write so unspecified fields survive despite Bookeo's PUT taking the full customer. This meaningfully softens the destructive interpretation. It omits permission/auth requirements and return behavior, keeping 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?

Three tight sentences with zero filler: purpose first, then the important merge-semantics caveat, then the underlying API call. Every sentence earns its place and the critical information 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 an 11-param mutation with no output schema and a low-coverage schema, the description covers the single most important behavioral fact (safe partial update). It could do more on param-level guidance and what the response returns, but the core decision-relevant information is 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 description coverage is low (27%) across 11 params including nested phoneNumbers and streetAddress objects, yet the description names no fields beyond the vague 'contact details'. It does clarify that only supplied changes are applied, which informs partial-update usage of params, but does not compensate for the coverage gap.

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 ('Update a customer's contact details') and the underlying API mapping (GET then PUT /customers/{id}), which immediately distinguishes it from sibling bookeo_create_customer and bookeo_get_customer. An agent can identify the operation without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the context (modifying an existing customer) but never states when to choose this over bookeo_create_customer or bookeo_update_booking, and gives no prerequisites or exclusions. Usage is inferable from the verb but not explicitly guided.

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