booqable

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

Annotations only supply destructiveHint=true, so the description's disclosure that booking creates a planning AND a line and allocates inventory is genuine added context about mutation side effects. It stops short of explaining why the operation is flagged destructive, what happens on shortage, or any permission 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 tightly written sentences with the core action front-loaded and the default-merging rule immediately after. The trailing API endpoint reference ("POST /api/4/order_fulfillments with a book_product action") is implementation detail an agent rarely needs and is the one non-earning element.

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, yet the description says nothing about what the call returns (e.g., created line/planning identifiers) or how shortage confirmation surfaces. For a mutating booking tool with six parameters, that leaves a real gap, though the core mechanics are covered.

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 mode enum is already fully documented in the schema, so parameter meaning is carried structurally. The description only restates the infer_planning default, adding nothing beyond what the schema already says.

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 ("Add a quantity of a product to an order") and goes further by stating the side effects ("allocating inventory (creates a planning and a line)"). However, it never names or contrasts itself with a sibling such as update_order or booqable_list_plannings, so an agent must infer the boundary 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?

"By default adds to an existing planning for the same product if there is one" gives useful default behavior, but the description never says when to prefer this tool over update_order or create_order, nor when to avoid it. Usage is implied rather than stated, and the mode alternatives live only in the schema.

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, but the description still adds genuine behavioral value: it names the returned fields `available` and `plannable` and explains that plannable can exceed available when shortage is allowed. That semantic distinction is not obtainable from annotations or schema. It stops short of a 5 by omitting any rate-limit or partial-result behavior.

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

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

Three short sentences, front-loaded with the core purpose, then return semantics, then the prerequisite pointer and endpoint. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description usefully explains the two return fields, and it covers the location-id prerequisite. What it lacks is any routing against the sibling availability/calendar tool and pagination or batch-size context (e.g. the 50-product cap already in 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%, including the nuanced note that `from`/`till` must be expressed in local time written as UTC. The description adds no parameter-level meaning beyond that, so the baseline 3 for full schema coverage 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: 'How many units of one or more products can be booked for an exact period at a location.' An agent knows exactly what it computes. However it does not name the sibling it differs from (booqable_get_availability_calendar), so sibling differentiation is absent, keeping it short of a 5.

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

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

Provides a useful prerequisite pointer ('Get location ids from booqable_list_locations'), which is real usage context. But there is no when-to-use/when-not guidance and no comparison to the closely related booqable_get_availability_calendar, leaving the agent to infer which availability tool fits the situation.

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 destructiveHint=true but say nothing else; the description does not add the behavioral detail the annotations omit, such as duplicate-email handling, minimum required fields, permission scope, or what is returned. It effectively restates the title and adds only a raw HTTP endpoint. No contradiction with annotations, since an insert is a write.

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

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

Two short sentences with the action front-loaded and no filler. The trailing API route adds traceability rather than bloat, though it does not help the agent invoke the tool more accurately.

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 with no output schema, the description omits the essentials: which fields matter beyond the required name, whether duplicate customers are rejected, and what the caller gets back (e.g., the new customer ID). The endpoint string does not compensate for these gaps.

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

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

Schema description coverage is 100%, so all six parameters (name, email, tag_list, legal_type, discount_percentage, email_marketing_consented) are already documented in the schema. The description adds no extra meaning, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Create a new customer') and adds the backing endpoint, so an agent knows exactly what operation this performs. It does not differentiate from siblings such as booqable_update_customer or booqable_create_order, though the tool name largely carries that distinction.

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

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

There is no guidance on when to use this tool versus booqable_update_customer or booqable_get_customer, and no prerequisites (e.g., whether the customer must not already exist, whether email is required for certain flows). The description is limited to a bare statement of action.

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 provide only destructiveHint=true and a title, so the description carries most of the burden. It usefully discloses that the note is internal (not customer-facing) and exposes the backing endpoint POST /api/4/notes, but says nothing about permissions, failure modes, or whether notes are editable/deletable afterwards. Note the mild tension: "attach" reads as additive while the annotation flags destructive behavior, though this is not an explicit contradiction.

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 written sentences: purpose first, endpoint second, zero filler. Nothing 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?

For a simple 3-parameter create with full schema coverage and no output schema, the description covers what the tool does and where it writes. It stops short of stating visibility guarantees or the create-vs-list relationship, but nothing critical for a correct call 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 body, owner_id and owner_type are already documented. The description's loose list of owner types adds only marginal color beyond the enum already present in the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Attach an internal note") and enumerates the record types it can attach to, which matches the owner_type enum. It implicitly contrasts with the sibling booqable_list_notes, but never names it or any other sibling, so 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 guidance on when to use this versus booqable_list_notes or the update/create siblings, no prerequisites (e.g., the owner record must already exist), and no exclusions. Usage is only implied by the verb.

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

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

Annotations only give destructiveHint=true, so the description usefully adds that the result starts empty and that locations 'default to the first active location' — a default not present in the schema. It still leaves auth requirements and the semantics of the destructive hint unexplained, so it is good but not complete.

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, each earning its place: what is created, the follow-up sequence, and the location default, plus the API endpoint. Nothing is wasted and the operation 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?

There is no output schema, but the description stays silent on what the call returns (notably the order id needed for the named follow-up tool booqable_book_product). Otherwise the prerequisites, defaults, and workflow are adequately covered for a seven-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 coverage is 100% with rich per-parameter descriptions, so the schema already carries the load; baseline 3 applies. The only added param meaning is the start/stop location default behaviour, which covers just one aspect of one pair of the seven parameters.

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 an EMPTY order for a rental period') with a scope qualifier ('EMPTY') that immediately separates it from booqable_update_order and booqable_book_product. The status constraint '(status new or draft)' further pins down the operation.

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

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

Clearly routes the agent through the follow-up workflow by naming the sibling tools booqable_book_product and booqable_transition_order_status and the order in which to call them. It does not say when to prefer this over alternatives like booqable_update_order, so it stops short of 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 safe-read profile, so the description's value-add is the returned shape: per-day status values (available/partial/unavailable) and bookable quantity. That is genuinely useful since there is no output schema. It omits pagination, timezone/location scoping behavior, and any rate-limit context.

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

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

Two sentences, zero filler, with the returned data described first and the API mapping second. Every clause carries information an agent can 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 read-only, no-output-schema tool, the description covers scope, return fields, and status vocabulary. It leaves location_id's effect (does it scope the calendar?) and any result-size limits unaddressed, but nothing critical 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% (year, month, quantity threshold, product_id UUID, location_id all documented), so the baseline is 3. The description adds no syntax, format, or constraint detail for any of the five parameters beyond what the schema already states.

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

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

States a concrete verb+resource+scope: day-by-day availability for one product over a month, and enumerates what comes back (status, bookable quantity). It implicitly distinguishes itself from the sibling booqable_check_inventory_availability via the calendar/month framing and endpoint mapping, but never names that sibling explicitly.

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

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

Usage is only implied through the endpoint hint (GET /api/4/availabilities with subject_type=item), which signals it is the per-item monthly calendar lookup. No when-to-use or when-not-to-use guidance versus booqable_check_inventory_availability or booqable_book_product, which cover adjacent availability concerns.

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 naming the returned data (name, currency, default timezone, address) and framing the call as a cheap credential-verification probe, which is genuinely useful behavioral context for a tool with 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 compact sentences with the resource and payload listed first, the practical use case second, and a trailing endpoint reference. Every clause carries information; nothing 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?

With no output schema and no parameters, the description compensates by enumerating the returned fields and explaining the call's purpose. An agent has everything it needs to invoke this correctly 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies the call is scoped entirely by the auth token rather than by user-supplied 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?

States a specific verb and resource ('Fetch the Booqable account this token belongs to') and even enumerates the returned fields plus the underlying API endpoint. No sibling tool touches company/account data, so it is trivially distinguishable from the order, customer, and product 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?

Provides a concrete use case — 'a cheap way to confirm the slug and token work' — which tells the agent when this call is worthwhile, e.g. as a connectivity/credential sanity check. It offers no explicit exclusions or named alternatives, but no sibling competes for this purpose.

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

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

readOnlyHint=true already declares the safety profile, and the description adds genuinely useful behavioral detail beyond that: the default sideloading of properties (addresses, phone, custom fields) and the specific aggregates returned. It stops short of noting error behavior for missing IDs.

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 with the return payload front-loaded before the endpoint citation; every clause carries information and nothing is repeated from 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?

With no output schema, the description usefully enumerates the returned fields, and readOnly annotations cover safety. A little more on the sideload override or failure behavior would make it fully self-contained.

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 both parameters are already documented, including the format of include. The description confirms the default sideload behavior, which adds marginal meaning, 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 (Fetch) and resource (one customer), and enumerates the payload (order count, revenue, balance due), which distinguishes it cleanly from sibling booqable_list_customers. The endpoint reference pins the resource further.

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' versus the list sibling, but there is no explicit when-to-use/when-not statement, no prerequisites, and no mention of alternatives such as list_customers for bulk retrieval.

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, but the description adds real behavioral context: it declares which relationships are sideloaded by default (customer, lines) and how to override that default. It does not cover auth requirements or response shape depth, 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?

Two tight sentences with the primary action and returned data front-loaded, followed by the override mechanism and an API reference. No filler, every clause earns its place.

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

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

With no output schema, the description correctly compensates by naming the returned data (totals, deposit, payment state) and default sideloads. It is complete enough to call correctly; only the exact sideload default for the payment/document relationships could be tighter.

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 value beyond the schema by disclosing the default inclusion behavior ('customer and order lines by default') and listing valid sideload values, which the schema only generically hints at.

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 order') and enumerates the returned payload fields (totals, deposit, payment state). The singular 'one order' implicitly distinguishes it from the sibling list_orders without needing 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 only implied: when you have an order_id and need the full record. There is no explicit when-to-use versus list_orders or update_order, nor any stated prerequisites or rate-limit caveats.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /api/4/customers) but no further behavioral context such as default page size behavior, auth requirements, or result limits beyond a bare endpoint reference.

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 compact sentence front-loads the purpose and the filter options, followed by a short endpoint citation. It is appropriately sized, though the raw endpoint string is marginal value for an agent.

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

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

For an 8-parameter, all-optional list tool with a fully documented schema and no output schema, the description is sufficient: filters and search modes are surfaced and the schema covers the rest. Minor gaps remain around pagination defaults and auth, but nothing critical blocks correct invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented, including exact-match semantics for 'email', free-text for 'q', and descending sort syntax. The description only summarizes the same filtering surface, adding no 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 and resource ('List customers') plus the filtering surface (name/email search, email/tag/archived filters). It reads clearly against the get_customer/create_customer siblings, though it doesn't name any of them explicitly to reinforce the distinction.

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 implies when to use it by describing the optional search/filter modes, which helps an agent pick the right query. But there is no explicit when-not guidance, no mention of alternatives (e.g., get_customer for a single record), and no statement of 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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description usefully adds that results include totals and payment status, but says nothing about pagination defaults, result size, or sideload behavior beyond what the schema states.

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

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

Two sentences, front-loaded with the resource and payload, followed by filters and the backing endpoint. No wasted text.

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 endpoint with full schema coverage and no output schema, the description covers resource, payload contents, and filter dimensions. Only minor gaps remain regarding pagination and sideloading, which the schema partly 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 every parameter is already documented in the schema (including enums for status and document_type). The description's filter listing adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (invoices, quotes, contracts) plus what each record carries (totals, payment status). This clearly distinguishes it from siblings like booqable_list_orders and booqable_list_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 description names the filter dimensions (type, order, customer, status), which implies when the tool is useful, but gives no explicit when-to-use/when-not guidance or alternatives among the many list_* 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 return-shape context (address, pickup/delivery capability) and downstream relevance, but says nothing about pagination behavior or default page size, which are left to the schema.

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

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

Three compact sentences with the resource front-loaded and the API endpoint last. Efficient, though the final endpoint sentence adds little for an agent choosing a tool.

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

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

For a simple read-only list operation with fully documented parameters, the description is sufficient. It sketches the returned fields even without an output schema, though it omits pagination expectations.

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

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

Schema description coverage is 100%, so page, page_size, and archived are fully documented in the schema. The description adds no parameter-level meaning beyond that, 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 (List) and resource (pickup/return locations) and even names representative subtypes (warehouses, stores). It is uniquely distinguishable because no sibling tool lists locations, though it doesn't explicitly contrast itself with 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?

It hints at downstream usage ('Location ids are needed for availability checks and orders') but never states a when-to-use rule or an alternative to prefer. No sibling performs this function, so implied usage is the most an agent gets.

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 tells the agent this is a safe read, so the description has a lower burden. It does add the useful fact that notes are 'internal' and maps to GET /api/4/notes, but says nothing about pagination behavior or result volume.

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

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

Two short sentences: the purpose and scope come first, the API mapping second. Every clause carries information and 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-only list tool with full schema coverage and a readOnlyHint annotation, the description covers what an agent needs to select and call it. The only omission is any hint about paginated result shape, which is minor given no output schema exists.

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 owner_id, owner_type, page and page_size each documented in the schema, including the enum of owner types. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb ('List') plus resource ('internal notes') and scopes it to records of several owner types. It is clearly distinguishable from booqable_create_note by the verb, though it never names the sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative booqable_create_note or of any filtering/retrieval conditions. Usage is only implied by the verb 'List'.

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 the upstream endpoint (GET /api/4/orders), which is mild context, and says nothing about pagination behavior, defaults, auth scope, 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?

Two sentences, no filler, and the scope statement is front-loaded before the filter list. The trailing API path is compact enough not to bloat the definition.

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?

Filter selection is well covered, but with no output schema the description should at least hint at the response shape (order objects, page/page_size pagination) and it does not. For a 13-parameter list tool the filtering story is complete while the return story is absent.

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 with type, defaults and enums. The description's filter recap (q, status, payment status, customer, rental period) merely restates what the schema provides, earning the baseline 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 (List) and resource (rental orders), and enumerates the filter dimensions, which makes it immediately distinguishable from the singular booqable_get_order and from other list_* siblings. It stops short of naming any sibling explicitly, so it lands at clear-but-not-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 description implies when the tool is useful by listing filterable facets, but it never states when to prefer this over booqable_get_order or the other list_* endpoints, nor does it give any exclusions or prerequisites. Usage is inferable rather than 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 already declare readOnlyHint=true, but the description adds real value by asserting 'this server never moves money', which clarifies the semantic boundary beyond the flag and rules out any mutation expectation. It also enumerates the returned fields, aiding interpretation.

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: capability, filtering, and the read-only assurance plus API path. No redundant restatement and the scope constraint is front-loaded.

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

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

With no output schema, the description usefully names the returned fields (amount, deposit, currency, provider, status), partially compensating. All parameters are schema-documented, so the agent has enough to invoke correctly; only pagination behavior across pages is 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 seven parameters are already documented with defaults, ranges and enum values. The description's mention of the three filter dimensions adds nothing the schema does not already carry; 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), enumerates the subtypes covered (charges, authorizations, refunds), and lists the returned attributes. An agent can distinguish this clearly from order- or customer-focused 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?

Gives clear context for use — filter by order, customer or payment type — and reassures that it is read-only. It does not name an alternative tool or state when not to use it, so it stops short of full routing 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 readOnlyHint=true, so the safety profile is covered. The description adds meaningful resource semantics (started/out vs stopped/returned counts, product-order mapping), but does not disclose pagination behavior, sorting/sideloading capabilities, or any auth/rate-limit context for this read 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 tightly written sentences plus the underlying endpoint. The core definition is front-loaded, the filter sentence follows logically, and there is no filler text.

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 a fully described 10-parameter schema and no output schema, the description gives enough context to understand the resource and filtering dimensions. It omits advanced options like include (sideloading) and sort, but those are documented in the schema, so the gap is 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% and all 10 parameters are individually documented there. The description's mention of filtering by 'order, product, or reservation window' mirrors order_id, product_id, and the starts_at/stops_at parameters but adds no syntax or format details 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 (plannings) and then defines what a planning actually represents: which product is booked on which order, quantity, timing, and started/stopped counts. This is far more specific than restating the name, and no sibling tool covers the same resource.

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 'Filter by order, product, or reservation window,' which implies the filtering scenarios the tool supports, but it never states when to choose this tool over alternatives (e.g. list_orders or get_availability_calendar) or any prerequisites. Usage is implied rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST endpoint (GET /api/4/product_groups), which is mild context, but says nothing about pagination limits, default page size behavior, or auth requirements. Adequate but not enriching 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?

Three short, front-loaded clauses with no filler: what it lists, the domain definition, and the endpoint. Every sentence earns its place, though the endpoint reference is marginally redundant for an agent that already knows the tool 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 read-only list tool with no output schema, the description usefully enumerates the fields a group carries and clarifies the group/product hierarchy. It is missing only filtering/pagination behavior caveats, which is a minor gap given the fully covered 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 eight parameters (q, tag, page, sort, include, archived, page_size, product_type) are already fully documented in the schema. The description adds no parameter-level meaning, 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 ('List product groups') and immediately defines what a group is (catalogue entries with name, SKU, product type, tracking type, pricing). The clause 'A group holds one or more bookable products (variations)' distinguishes it conceptually from the sibling booqable_list_products without the agent needing to open 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 group-vs-product relationship implies when to reach for this tool, but there is no explicit routing guidance such as 'use booqable_list_products to fetch individual bookable products.' Usage is inferable but not stated, which is the definition of a 3.

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

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

readOnlyHint=true already declares this is a safe read, so the description's burden is lower. It adds the context that returned product ids feed availability checks and booking, but says nothing about pagination behavior, default paging, or the shape of results for a collection 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 tightly written sentences with the purpose and the downstream use case front-loaded, plus the endpoint in a compact tag. Nothing is wasted or buried.

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

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

For a read-only list tool with fully documented parameters and no output schema, the description plus schema gives an agent everything needed to call it. Only minor gaps remain (no note on pagination semantics or result ordering defaults).

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

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

Schema description coverage is 100% and every one of the 8 filter/paging parameters is documented in the schema itself. The description adds no filtering, sorting, or paging semantics beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb+resource ('List bookable products') and immediately scopes the resource as 'the variations inside product groups', which separates it from the sibling booqable_list_product_groups. An agent can tell what this returns 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?

Explicitly routes the agent onward: 'Use a product id for availability checks and booking', implying this is the discovery step before booqable_check_inventory_availability or booqable_book_product. It gives clear context but does not state exclusions or explicitly name those sibling tools by 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?

Beyond the destructiveHint annotation, it discloses side effects (reserving items, assigning an order number), the irreversibility of canceling, and that Booqable validates the current status. The shortage-confirmation behavior is also flagged.

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

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

Front-loaded with the core transitions and dense with useful constraints; every clause carries a constraint. Slightly packed—the parentheticals and endpoint string add length—but nothing is 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 mutation with no output schema, the description covers the transition graph, the revert caveat, the cancel exclusion, and side effects. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: revert is required specifically for started/stopped, and reserving may trigger a shortage warning. It stops short of detailing confirm_shortage beyond the schema text.

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 precise verb+resource ('Move an order between statuses') and enumerates the concrete transitions supported, which lets an agent distinguish it from the generic sibling booqable_update_order. The POST endpoint confirms the operation.

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

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

Explicitly says what is NOT offered (canceling, because Booqable cannot un-cancel) and constrains when started/stopped are legitimate (only with revert: true), plus notes that those states are normally reached via pickup/return. This is when/when-not guidance an agent can act on directly.

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 mutation risk is known from structured data. The description adds one useful behavioral fact — that unpassed fields are left untouched — plus the underlying endpoint. It still says nothing about permissions, reversibility of overwritten values, or validation/error behavior, which matters for a write tool.

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

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

Two compact sentences plus an endpoint reference, front-loaded with the field list and the partial-update rule. No filler, though the trailing API path is mildly redundant for an agent that keys off tool 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 7-parameter mutation with full schema coverage and a destructiveHint annotation, the description covers purpose, scope of change, and partial-update semantics. No output schema exists so returns need not be described; only auth/permission and failure behavior are 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?

Schema description coverage is 100% with 7 documented parameters, so baseline is 3. The description restates the same field set the schema already documents (tags -> tag_list, default discount -> discount_percentage) without adding format, constraint, 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 (Update) and resource (customer) and enumerates the mutable fields (name, email, legal type, tags, default discount, marketing consent). It is clearly distinguishable from booqable_create_customer and booqable_get_customer on verb alone, though it never explicitly names those 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?

'Only the fields you pass change' communicates partial-update semantics, which is genuine usage guidance for calling it correctly. However, there is no statement of when to prefer this over siblings (e.g. create vs update), no prerequisites, and no exclusion 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?

With destructiveHint=true already set, the description adds meaningful behavior the annotation cannot convey: a date change may fail with shortage details, and a shortage warning is only overridable via a retry with confirm_shortage. It still omits whether updates are partial, merge or replace semantics for tags, and permission 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?

Three tight sentences, front-loaded with what changes and the risky interaction, followed by the endpoint reference. The trailing 'Booqable: PUT /api/4/orders/{id}.' restates the resource without adding agent-relevant detail, a minor inefficiency.

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

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

For an 8-parameter mutation tool with no output schema, the definition covers the mutable fields and the one non-obvious failure mode well. It would be stronger if it said whether the response returns the updated order and whether unsupplied fields are left untouched.

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; however, the description goes beyond the schema by explaining the failure/retry relationship that gives confirm_shortage its meaning, and by grouping the parameters into editable facets (period, customer, locations, tags).

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 (Change) and resource (an order) and enumerates the mutable facets: rental period, customer, locations, tags. This implicitly separates it from booqable_create_order and booqable_transition_order_status, which handles status, though no sibling is named explicitly.

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

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

It gives a concrete usage condition: moving dates can trigger a shortage, in which case the call fails with details and can be accepted by retrying with confirm_shortage: true. That is real when-to-use guidance, but it offers no explicit alternatives or exclusions versus related tools such as update_customer or transition_order_status.

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