Booqable MCP by usefulapi

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

Annotations only declare destructiveHint=true; the description goes further by disclosing the side effects (inventory allocation, creation of both a planning and a line) and the default merge behavior. It omits any statement about shortage/error handling, permissions, or what is returned.

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

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

Two tight sentences, front-loaded with purpose and effect before the default-behavior note. The trailing REST endpoint reference is mildly redundant for an agent but harmless and short enough to keep the response 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?

For a 6-parameter mutation tool with full schema coverage and no output schema, the description covers the operation's core behavior adequately. It does not describe the return payload (created planning/line identifiers) or failure modes, which leaves a small gap an agent would otherwise want filled.

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

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

Schema description coverage is 100%, so both the mode enum semantics and confirm_shortage are already fully documented in the schema. The description restates the default mode behavior but adds no syntax or meaning beyond what the schema provides, matching the baseline of 3.

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 (add/book) and resource (a quantity of a product to an order) plus the concrete effect (creates a planning and a line). This is clearly distinguishable from siblings like create_order or list_plannings.

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 the default behavior (reuse an existing planning for the same product) and the schema enumerates modes, which implies when each mode applies, but there is no explicit guidance on when to call this tool versus create_order, update_order, or other 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 the safety profile is covered. The description adds value beyond that by explaining the return semantics: `available` vs `plannable`, and that `plannable` can exceed `available` when shortage is allowed. It does not mention rate limits or whether results are cached, but for a read-only lookup this is solid.

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 core question the tool answers, followed by return semantics and the prerequisite lookup, and closing with the endpoint. No filler.

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

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

There is no output schema, so the description carries the burden of explaining return values, which it does via `available` and `plannable`. With readOnlyHint covering safety and the schema covering all parameters, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the non-obvious 'local time written as UTC' convention. The description restates the exact-period/location framing but adds no syntax or format detail 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?

States a specific resource (inventory availability) with a precise verb and scope: how many units of one or more products can be booked for an exact period at a location. This distinguishes it from the sibling booqable_get_availability_calendar by emphasizing an exact period rather than a calendar view, and it names the underlying API endpoint.

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

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

Provides a concrete prerequisite pointer ('Get location ids from booqable_list_locations'), which is the key routing information needed before calling. It never states when to prefer this over booqable_get_availability_calendar, so it lacks explicit alternatives/exclusions.

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

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

Annotations only supply destructiveHint=true; the description adds the endpoint path but nothing about duplicate-email handling, required permissions, whether the call is idempotent, or what the response returns. For a mutation with side effects, that is a thin behavioral picture, though the annotations carry the safety signal.

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

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

Two short front-loaded sentences with no filler; the action is stated first. The endpoint sentence is marginal utility but not wasteful.

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 6-parameter write tool with no output schema, the description omits what a successful call returns (e.g. the new customer's id), how validation errors surface, and any duplicate/precondition rules. The schema covers inputs, but the description leaves the mutation's outcomes unexplained.

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

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

Schema description coverage is 100%, with every field documented including the required name, the legal_type enum, and the discount bounds. The description adds nothing 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?

"Create a new customer" states a specific verb and resource, and naming the API endpoint (POST /api/4/customers) confirms the write semantics. It does not differentiate itself from siblings like booqable_update_customer or booqable_get_customer, but the intent is unmistakable.

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

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

There is no when-to-use guidance and no mention of alternatives such as booqable_update_customer for existing customers or booqable_list_customers/booqable_get_customer for lookups. An agent must infer the choice purely from the verb in the name.

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

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

Annotations supply destructiveHint=true and a title, so the safety bar is partly carried already. The description adds genuinely useful context by marking the note as 'internal' (visibility semantics not in the schema) and mapping to POST /api/4/notes, but it says nothing about permissions, whether notes can be edited/deleted later, or why a note-creation call is flagged destructive.

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

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

Two short sentences, with the purpose front-loaded and no wasted clauses. The trailing 'Booqable: POST /api/4/notes.' is close to filler, though it does give an API endpoint mapping an agent could use.

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 three-parameter create tool with no output schema, the description covers the essentials: what is created, where it attaches, and that it is internal. It omits what the call returns and any permission/visibility caveats, leaving it adequate but not fully self-sufficient.

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

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

Schema coverage is 100%, with each of the three required parameters (body, owner_id, owner_type) already documented in the schema and owner_type fully enumerated. The description adds nothing beyond a loose restatement of the owner types, 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 gives a specific verb+resource ('Attach an internal note') and enumerates valid targets (customer, order, product, other record), which is enough to distinguish it from the read-side sibling booqable_list_notes. It stops short of explicitly naming that sibling as the alternative, so it is clear but not sibling-differentiating.

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

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

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no mention of the obvious alternative (booqable_list_notes) or of which record types are appropriate. The word 'internal' hints at intent but the description never states the conditions under which a note should be created.

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

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

Annotations only carry destructiveHint=true, so the description does useful extra work: it discloses that the created order is empty, that locations fall back to the first active location, and that status 'new' vs 'draft' changes visibility/reservation behaviour. It does not explain why a create is flagged destructive or what the response returns, so it is good rather than exhaustive.

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

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

Two dense sentences plus an endpoint reference, with the most important constraint (EMPTY order) front-loaded and the chaining instructions immediately after. Nothing here is filler.

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

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

There is no output schema, so the agent must infer the return value; the description implies chaining but never states that the response yields the order id needed for booqable_book_product. Otherwise it covers scope, defaults and next steps adequately for a 7-parameter create tool.

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

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

Schema description coverage is 100% and the schema already explains the tricky UTC-as-local timestamp convention, status semantics and location ids in more detail than the description does. The description adds no parameter meaning 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 plus a scope qualifier that matters ('Create an EMPTY order for a rental period') and lists the accepted initial statuses. This clearly separates it from siblings like booqable_book_product, booqable_update_order and booqable_transition_order_status, which an agent can route between 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?

Explicitly prescribes the follow-on workflow: add products with booqable_book_product, then reserve with booqable_transition_order_status — that is real when-to-use-next guidance and implicitly tells the agent not to expect line items here. It never states when not to use this tool (e.g. versus update_order on an existing order), so it falls short of a full 5.

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

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

Annotations already establish readOnlyHint=true, so this is a safe read. The description adds genuine value beyond that: it enumerates the status values (available/partial/unavailable), notes a bookable quantity per day, and discloses the underlying API call, which is useful since there is no output schema.

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

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

Two tight sentences with zero filler; the purpose and return shape are front-loaded and the API detail is secondary. Every clause earns its place.

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

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

For a read-only, no-output-schema tool, the description covers scope, returned statuses, and quantity semantics well. It is only slightly short of complete in not clarifying how it relates to the sibling availability tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including the quantity threshold and location_id. The description adds no syntax or format detail beyond what the schema provides, 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+scope: day-by-day availability for one product over a month, with the returned fields (status, bookable quantity per day). This is clear, but it does not name or distinguish itself from the sibling booqable_check_inventory_availability, which an agent could easily confuse it with.

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 a per-month calendar lookup but gives no explicit when-to-use guidance and never names an alternative or exclusion. With booqable_check_inventory_availability sitting right next to it, the agent is left to infer which one answers which question.

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 covers the safety profile, yet the description still adds real context: the result is scoped by the calling token, it is a low-cost call suitable for smoke-testing credentials, and it returns a fixed set of account fields. It does not mention error behavior on an invalid token or rate limits, 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?

Three short clauses: what it returns, why to call it, and the backing endpoint. Nothing is padded and the return contents are front-loaded before the usage hint.

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 no parameters, the description carries the burden of describing the response and does so (name, currency, timezone, address). An agent has everything needed to call it with an empty object and interpret the result.

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

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

Zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly signals that no input is required by describing the token-derived scope instead of any arguments.

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 ('Fetch the Booqable account this token belongs to') and enumerates what comes back (name, currency, default timezone, address). This is clearly distinguishable from every sibling, which all operate on customers, orders, products, or documents rather than the account itself.

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

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

Explicitly frames the use case: 'A cheap way to confirm the slug and token work,' which tells the agent when to reach for it (connectivity/auth verification) versus a real data query. It stops short of naming when *not* to use it or an alternative, but for account metadata there is no competing sibling to route to.

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, so the description's remaining job is to add context, which it does: it discloses the default sideloading of properties and the computed fields (order count, revenue, balance due). It omits considerations like missing-customer behavior, but for a simple read this is a solid add.

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

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

Two tightly packed sentences that front-load the payload description and end with the API mapping. No filler, 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 takes on the burden of explaining the return and does so at a summary level (order count, revenue, balance due, properties). It stops short of describing the response shape or how the sideloaded data is nested, but is adequate for a single-entity fetch.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it reveals that `properties` is included by default and what those properties contain (addresses, phone, custom fields), which the schema's generic 'comma-separated relationships to sideload' does not convey.

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

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

States a specific verb (fetch) and resource (one customer), and enumerates the included data (order count, revenue, balance due, sideloaded properties). This clearly separates it from sibling booqable_list_customers and booqable_get_company.

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

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

Usage is implied by the singular 'one customer' and the required customer_id, but the description never states when to prefer this over booqable_list_customers, booqable_get_order, or the sibling retrieval tools, nor any prerequisites for knowing the customer 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, and the description adds genuinely new behavior: which relationships are sideloaded by default and how to change them. It stops short of covering error behavior for unknown ids or any rate limits, so it is good but not exhaustive.

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

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

One dense sentence that front-loads the resource and return content before the override detail. The trailing raw endpoint reference ('GET /api/4/orders/{id}') is mildly redundant but cheap and useful for doc mapping.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does so (totals, deposit, payment state, default sideloaded relations). Minor omissions remain around failure modes and whether the include string is additive or replacing for non-default relations.

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 example relationship list is duplicated from the schema, so the schema does most of the work. However, the description adds the fact that customer and lines are sideloaded by default and that include overrides that default — a semantic the input schema never states.

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

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

States a specific verb (Fetch) plus resource (one order) and enumerates what comes back: totals, deposit, payment state. The singular 'one order' plus the required order_id cleanly separates it from the plural sibling booqable_list_orders 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 explains default sideloading and how to override it via include, which is practical guidance, but it never says when to call this instead of booqable_list_orders or booqable_get_customer, nor any prerequisite (e.g. valid order id). Usage is implied rather than directed.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add beyond that. It contributes the underlying API path (GET /api/4/customers), which helps an API-aware agent map to docs, but stays silent on pagination limits, total-count behavior, or rate limiting — the traits that actually matter for a list endpoint.

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

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

Two short sentences, front-loaded with the operation and its filters. The trailing endpoint reference is compact and optionally useful rather than filler, though it is the least agent-relevant clause.

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

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

Eight parameters but all documented at 100% coverage in the schema, and no output schema means return shape is out of scope for the description. Combined with readOnlyHint covering the safety profile, the definition is adequate; only the absence of any result-count or pagination guidance keeps it from a 5.

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 (q, tag, page, sort, email, include, archived, page_size) are already self-documenting. The description's summary list duplicates those fields at a higher level without adding format details (e.g. how sort syntax interacts with pagination), so baseline 3 is appropriate.

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

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

The description gives a specific verb+resource (list customers) and enumerates the search/filter dimensions, plus the underlying endpoint. It stops short of explicitly distinguishing itself from siblings like booqable_get_customer or booqable_create_customer, so the scope is clear but not sibling-differentiated.

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

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

Usage is implied by 'List customers' — the agent can infer this is the collection endpoint versus booqable_get_customer for a single record, but the description never says so. No when-not-to-use guidance, no prerequisites, and no mention of pagination behavior for a list of potentially hundreds of customers.

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. The description adds useful content context (results include totals and payment status) and names the underlying endpoint, but says nothing about pagination limits or result ordering behavior beyond what the schema documents.

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

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

Two compact sentences plus a one-line endpoint reference; the core capability and the filter axes are front-loaded with no filler. Every sentence carries information.

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

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

For a 9-parameter, zero-required read tool with no output schema, the description covers what is returned (documents with totals and payment status), how to narrow results, and the API path. It lacks explicit pagination/output-shape guidance, but the schema handles the parameters and there is no output schema to compensate for.

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 9 parameters is already documented (including enum values for status and document_type). The description only restates the filterable axes (type, order, customer, status), adding no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List invoices, quotes and contracts'), plus what the results contain ('totals and payment status'). It is distinguishable from siblings because no other list tool covers documents, though the description never explicitly contrasts itself with the other booqable_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?

'Filter by type, order, customer or status' implies when the tool is useful (narrowing a document set) but there is no explicit when-to-use/when-not guidance or pointer to an alternative such as fetching a single document via an order. Usage is inferable but not stated.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds the underlying endpoint (GET /api/4/locations) and notes the downstream dependency on location ids, which is modest extra context. It does not mention pagination behavior or result volume, though page/page_size in the schema mitigate that.

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

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

Three compact sentences with the resource and scope front-loaded, followed by usage context and the API mapping. The endpoint sentence is marginally redundant for an MCP agent but is short enough not to distract.

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?

Despite having no output schema, the description indicates the shape of returned data (address, pickup/delivery capability) and why the ids matter. Pagination semantics are not restated, but the schema already covers them, so the definition is adequate for a simple read-only list tool.

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

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

Schema description coverage is 100%, so page, page_size, and archived are already fully documented with ranges and defaults. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (pickup/return locations), then qualifies it with concrete examples (warehouses, stores) and the fields returned (address, pickup/delivery capability). No sibling tool lists locations, so the agent can identify this unambiguously.

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

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

The description explains downstream context - 'Location ids are needed for availability checks and orders' - which tells the agent when this tool is a prerequisite. It stops short of naming explicit alternatives or exclusions, but there are no location-listing siblings to disambiguate against.

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 only that the notes are 'internal' and the underlying endpoint, which is useful but thin; nothing about authorization requirements or pagination behavior is disclosed.

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, purpose first, with no filler. The trailing 'Booqable: GET /api/4/notes' is a cheap implementation detail but doesn't impede comprehension.

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 full schema coverage, no output schema, and a read-only annotation, the description only needs to convey purpose and scope, which it does. Pagination and return-shape detail live in the schema/annotations, so the brief text is nearly sufficient.

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% – owner_id, owner_type (with its enum), page and page_size are all documented in the schema. The description merely restates the owner-type mapping that the enum already provides, adding no format or usage nuance.

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 ('internal notes'), plus the scope of records they hang off ('customer, order, product or other record'). It contrasts implicitly with the write sibling booqable_create_note, but never names it, so sibling 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?

The description says what notes are but gives no when-to-use or when-not-to-use guidance relative to booqable_create_note or the other list_* tools. The fact that a separate create_note tool exists is not acknowledged, so the agent gets no routing signal.

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, non-mutating read. The description adds the upstream endpoint mapping (GET /api/4/orders) but says nothing about result shape, result limits, or how pagination/total counts behave beyond what the schema already documents for page and page_size.

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

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

Two tight sentences with the core action front-loaded, followed by the filter surface and the endpoint. The filter enumeration is partly redundant with the schema, but it is structured and readable rather than padded.

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

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

For a read-only list tool with all 13 parameters fully documented and pagination covered in the schema, the description supplies what is missing: the filterable dimensions and the underlying API. The absence of an output schema means return shape/pagination semantics remain unstated, which is the main residual gap.

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

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

Schema description coverage is 100%, so every one of the 13 parameters is already documented, including the enum values and ISO 8601 formats. The description restates the filter categories at a high level and adds only the useful note that free-text search covers order number, customer name/email/address, tags and custom fields. Baseline 3 is correct 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 ("List rental orders") and enumerates the filterable dimensions, which clearly separates it from singleton siblings like booqable_get_order. It stops short of naming a sibling alternative explicitly, so it is clear but not maximally differentiating.

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 filter list implies the tool is for browsing/searching orders, and it is obvious enough that listing pairs with booqable_get_order. But there is no explicit when-to-use statement, no guidance on when not to use it (e.g. when you already have an id), and no alternatives named.

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 goes further with "this server never moves money," which is meaningful disambiguation for payments — it tells the agent that refunds and authorizations are only listed, never initiated — and it names the fields returned. It stops short of describing pagination or response shape.

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

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

Two compact sentences with the resource and result contents front-loaded, followed by filtering. The trailing "Booqable: GET /api/4/payments" endpoint mapping is mildly redundant but cheap and useful for grounding.

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 seven-parameter, zero-required list tool with no output schema and no nested objects, the description covers what is returned, the filter dimensions, and the read-only guarantee. Pagination behavior is left entirely to the schema, which is acceptable given the documented page/page_size 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?

Schema description coverage is 100%, with each of the seven parameters documented including the payment-type enum, so the schema carries the load and the baseline is 3. The description's mention of order/customer/type filters loosely mirrors those parameters without adding format or syntax detail beyond the schema.

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

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

States a specific verb (List) and resource (payments), then enumerates what the resource contains — charges, authorizations, refunds, plus the fields carried. That enumeration clearly separates it from siblings like booqable_list_orders or booqable_list_documents.

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 by order, customer or payment type" conveys what the tool is good for, but it reads as parameter enumeration rather than when-to-use guidance. There is no statement of when to prefer this over a sibling lookup or any exclusions, so usage is only implied.

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds genuinely non-obvious domain semantics, decoding what a planning records and what "started (out)" vs "stopped (returned)" mean, plus the underlying endpoint (GET /api/4/plannings). It does not mention pagination behaviour, but that is the only notable 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 tight sentences: the resource definition comes first, the filter affordances second, and the endpoint reference last. There is no boilerplate and every clause carries information an agent would otherwise have to infer.

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

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

With no output schema, the description usefully sketches what each planning contains (product, order, quantity, timing, out/returned counts), and the endpoint reference is a bonus. It is nearly complete for a read-only list tool, though it never says whether results are paginated or how large the default result set is (page_size's default of 25 lives only in the schema).

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

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

Schema description coverage is 100%, so all ten parameters are already self-documented, including types, ISO 8601 formats, and the 1-100 page_size bound. The description only restates the filter categories at a high level and adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (List) plus a domain-specific resource (plannings) and then defines that resource in terms of what it relates: product booked on order, quantity, timing, and out/returned counts. That definition is what separates it from siblings like booqable_list_orders and booqable_list_products, which cover the same underlying entities at a coarser level.

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 by order, product, or reservation window" hints at when the tool is useful, and the filters map cleanly onto order_id, product_id and the starts_at/stops_at bounds. However, it never states when to prefer this over sibling list tools (e.g., list_orders to view bookings, or get_order for a single order's detail), so the routing decision 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 declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /api/4/product_groups) and hints at returned fields in parentheses, but does not disclose pagination behavior, rate limits, or other operational traits beyond what the schema and annotations already imply.

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 front-loaded with the core purpose, followed by a concise clarification of the resource and a single endpoint reference. It is appropriately sized, though the raw endpoint line adds little for an agent invoking the MCP tool.

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

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

Given 8 optional parameters, no output schema, and only readOnlyHint annotations, the description provides key domain context about what a product group is and how it relates to bookable products. It falls short only on operational details like pagination behavior, which the schema already partially covers.

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 are well documented in the schema itself. The description adds no parameter-specific syntax or format details beyond what the schema provides, making the baseline score of 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?

States a specific verb (List) and resource (product groups), then defines what a group is: catalogue entries with name, SKU, product type, tracking type, and pricing, and clarifies that a group holds one or more bookable products (variations). This distinguishes it from sibling list tools like booqable_list_products.

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 through the definition of a product group and its relationship to products, but does not explicitly state when to use this tool versus alternatives such as booqable_list_products or search-oriented tools. No exclusions or prerequisites are given.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds the underlying REST endpoint (GET /api/4/products), which is contextual but not behaviorally load-bearing, and it says nothing about pagination limits or result shape beyond what the schema's page/page_size fields imply.

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 purpose and the disambiguation, with no filler. The trailing API endpoint note is marginally useful and slightly padded but does not undermine the structure.

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 definition covers what an agent needs to call it. The main omission is any hint about the shape or pagination envelope of results, which the agent must discover at runtime.

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 (q, sort, include, archived, product_type, page, page_size, product_group_id) are already documented in the schema. The description adds no further syntax or semantic detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List bookable products') and immediately disambiguates the term by clarifying these are the variations inside product groups, which separates it from booqable_list_product_groups. It does not name the sibling directly, but the parenthetical does the differentiation work.

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 a product id for availability checks and booking' tells the agent what the returned ids feed into (booqable_check_inventory_availability, booqable_book_product), which implies the reason to call this tool. There is no explicit when-to-use-vs-alternative framing, such as how this relates to booqable_list_product_groups or when archived filtering should be preferred.

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 provide destructiveHint=true; the description carries the rest, disclosing real side effects (reserved reserves the items and assigns an order number) and an unrecoverable action (canceling cannot be undone). It does not state whether the status change itself is reversible or what auth/permissions are needed, but it adds substantial context beyond the annotation.

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

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

Dense but front-loaded and every clause carries information (transition map, revert rule, cancel exclusion). The trailing 'Booqable: POST /api/4/order_status_transitions' is endpoint trivia that an MCP caller cannot use, a minor waste.

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 the state machine, constraints, and side effects well for a destructive mutation with no output schema. It leaves out what is returned on success (updated order vs. confirmation) and any failure modes such as an invalid from/to pair or shortage rejection.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it by giving the valid transition graph, the revert requirement for started/stopped, and the reserving-time purpose of confirm_shortage. It adds genuine transition semantics the enum list alone does not convey.

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

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

Specific verb+resource ('Move an order between statuses') with an explicit state graph (new→draft, draft→reserved, stopped→archived). It never names the closest sibling, booqable_update_order, so an agent must infer why a status change must go through this tool rather than a generic field update.

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?

Strong conditional guidance: revert: true for backward moves, started/stopped only valid with revert, and an explicit exclusion (canceling is not offered because Booqable cannot un-cancel). It stops short of naming an alternative tool for any case, so it lands at 4 rather than 5.

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

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

Annotations only declare destructiveHint=true; the description adds the important behavioral fact that this is a partial (patch-style) update where unspecified fields are preserved, which prevents accidental full overwrite. It also names the underlying endpoint (PUT /api/4/customers/{id}). It does not cover auth requirements, error behavior for an unknown id, or whether the updated record is returned.

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

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

Two compact sentences: the field list and partial-update rule come first, then the API mapping. Every clause carries information; no padding or 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 mutation tool with only a destructiveHint annotation and no output schema, the description covers the fields and partial-update semantics but omits what happens on invalid customer_id, whether the response returns the updated customer, and any permission requirements. Adequate to call correctly, but not complete.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the legal_type enum and the 0-100 discount range. The description merely names the fields in prose, adding no syntax, format, or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (update) and resource (customer) and enumerates the mutable fields (name, email, legal type, tags, discount, marketing consent). This is clearly distinguishable from create_customer, get_customer, and update_order among siblings.

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

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

Implies usage (modify an existing customer) and the partial-update rule 'Only the fields you pass change' tells the agent it need not resend all fields. However, there is no explicit when-to-use vs alternatives guidance, e.g. that fetching via get_customer first is prudent, or that create_customer is the tool for new records.

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 destructiveHint already set to true, the description adds important behavioral detail beyond annotations: moving dates can trigger a shortage, the call fails with shortage details, and a warning can be accepted by retrying with confirm_shortage: true. It does not cover auth requirements or whether other fields are preserved, but the shortage/retry behavior is a meaningful addition.

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

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

Three sentences, front-loaded with the purpose, then the critical shortage behavior, then the underlying API endpoint. Every sentence carries useful 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?

For an update tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the main mutation, the key failure mode, and the retry parameter, though it does not clarify authentication needs or partial-update semantics.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including confirm_shortage and the date formatting caveat. The description groups the changeable fields conceptually but adds no syntax, format, or constraint detail beyond what is already in the schema.

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

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

The description states a specific verb and resource: 'Change an order's rental period, customer, locations or tags.' It distinguishes the operation from siblings like booqable_get_order, booqable_create_order, and booqable_transition_order_status by naming the mutable fields.

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 when to use it by listing the fields it can change, and it gives specific retry guidance for shortage warnings via confirm_shortage: true. However, it does not compare this tool against alternatives such as booqable_transition_order_status or state when not to use it.

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