Smoobu MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so 'Read-only, books nothing' is largely confirmatory. The real added value is disclosing the failure semantics returned ('minimum stay, too many guests, arrival day, lead time...') and the endpoint mapping, which the annotations and absent output schema would otherwise leave opaque. It omits cost composition (fees/taxes/currency) and any rate-limit or auth notes.

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 front-loads the core outcome and its failure modes, followed by a two-word safety note and a compact endpoint citation. Every clause earns its place; 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?

With no output schema, the description does the necessary work of explaining what comes back (bookable properties plus reasons for the rest). It is slightly under-specified on what 'total price' includes (fees, taxes, currency) and does not mention pagination or result caps for large property sets.

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 are already documented in the schema, including the customer_id lookup fallback and the 'omit apartment_ids to check all' behavior. The description adds nothing parameter-specific beyond the arrival/departure pairing, 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?

Starts with a concrete verb+resource ('Check which properties can be booked for an arrival/departure pair') and adds the value returned ('get the total price for each'). This is clearly separable from list_apartments (inventory) and get_rates (rate lookup) 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?

Usage is implied by 'Read-only, books nothing,' which signals this is the pre-booking check rather than the booking action (smoobu_create_reservation). However, it never explicitly names an alternative tool or states when not to use it, leaving the routing inference to the agent.

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

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

Annotations supply only destructiveHint=true, so the description carries real weight and delivers: channel-wide date sync side effects, the overlap failure mode, and the irreversibility ('no cancel'). It also discloses that required guest fields vary with the account's Form Content settings, which no structured field conveys.

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 action, then side effects, failure mode, and caveats in descending priority. Six sentences and every one contributes a distinct fact; the trailing API endpoint is the only mild redundancy.

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

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

For a 23-parameter mutation with no output schema and minimal annotations, it covers side effects, failure, and reversibility well. The remaining gap is the return value — with no output schema, telling the agent it receives the new reservation id would have closed the loop.

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 genuinely non-schema information: mandatory guest fields depend on the booking-tool Form Content configuration. That clarifies why only three fields are marked required and guides the agent on which of the 23 parameters matter.

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

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

States a specific verb+resource ('Create a reservation') and extends the scope to blocked periods, which the bare title omits. The create-vs-update boundary against smoobu_update_reservation is implicit in the verb, and the channel-sync sentence makes the operation's nature 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?

Gives clear context ('or a blocked period', fails on overlapping dates) and an explicit exclusion ('no cancel — cancel it in Smoobu'). It stops short of naming a sibling to run first (e.g., smoobu_check_availability) even though the overlap failure strongly implies one, so routing is left partly to inference.

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

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

readOnlyHint=true already declares the safe-read profile, so the description's remaining burden is low. It adds the field inventory returned by the call, but discloses nothing about error behavior for unknown/missing ids or auth requirements beyond the endpoint path.

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 resource and its payload, no filler, and it terminates quickly. The endpoint reference sentence is informative but largely restates what the name and annotations already imply, keeping it just short of maximally tight.

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

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

For a single-param read tool with annotations covering safety and no output schema, the description's field list effectively conveys what comes back, so an agent has everything needed to call and interpret it.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains apartment_id fully. The description adds no syntax, format, or lookup guidance beyond what the schema provides, matching the baseline 3 for fully documented params.

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 (fetch) plus resource (one property) with an enumerated payload, and the required apartment_id makes the singular scope unmistakable against the sibling smoobu_list_apartments. The trailing GET /api/apartments/{apartmentId} pins the exact upstream 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?

Usage is only implied: needing the full detail of a single known property. There is no explicit statement of when to prefer this over smoobu_list_apartments (e.g. to enumerate properties first) nor any exclusion or prerequisite 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 safety is covered. The description goes beyond that by disclosing what the payload contains, notably that every booking the guest has made is included, which is non-obvious and useful for deciding whether this single call can replace multiple lookups.

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

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

One front-loaded sentence carrying the verb, the identifier, the payload scope, and the underlying endpoint. No filler and nothing important is 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?

No output schema exists, and the description compensates by naming the payload contents, which is what an agent most needs for a single-param read. It omits error behavior for an unknown guestId, a minor gap for a tool of this complexity.

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 parameter is self-documented as 'The guest id', so the baseline is 3. The parenthetical '(the guestId on a reservation)' adds real disambiguation by tying the identifier to its source object, distinguishing it from a user or apartment id elsewhere in the API.

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 one guest by id') plus the exact scope of the returned payload (contact details, notes, every booking). The singular 'one guest by id' cleanly separates it from the sibling smoobu_list_guests without opening either schema.

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

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

The description implies the usage condition by saying it fetches by 'the guestId on a reservation', so an agent knows it needs an id in hand. However, it never explicitly says when to prefer this over smoobu_list_guests or what to do when the id is unknown, leaving routing to inference.

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

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

readOnlyHint=true already establishes the safety profile, so the description is not carrying that burden. It does add one genuinely useful behavioral detail — the encoding '0 = not available' — but says nothing about rate limits, auth, or edge cases on the date range.

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

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

A single sentence delivering resource, return fields, range semantics and multi-property scope, followed by a short endpoint reference. Front-loaded and free of filler.

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

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

With no output schema, the description usefully enumerates the returned quantities (nightly price, minimum length of stay, availability per date) so an agent knows what to expect. Parameter coverage is complete via the schema. Only the practical boundaries of the date range and the unit/currency of the price are left unstated.

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

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

Schema description coverage is 100%: all three parameters (apartment_ids, start_date, end_date) are documented in the schema, including the yyyy-mm-dd format. The description only restates 'one or more properties' and 'each date in a range', adding no syntax beyond the schema — the baseline 3 applies.

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

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

States a specific verb and resource ('Get the nightly price, minimum length of stay and availability ... for each date in a range, for one or more properties'), which tells an agent exactly what it returns. It does not differentiate itself from the sibling smoobu_check_availability, which covers overlapping ground, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus alternatives such as smoobu_check_availability, nor any prerequisites or exclusions. Usage can only be inferred from the resource being described.

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

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

readOnlyHint=true already establishes the safety profile, so the description's job is to add context beyond that — and it does, enumerating the concrete fields returned (prepayment/deposit status, channel reference id, guest-app URL) in the absence of an output schema. It stops short of noting auth scope or error behavior for a missing/invalid id.

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

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

One sentence, front-loaded with the action and lookup key, followed by the returned payload and the underlying API route. 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?

For a single-entity read with no output schema and one fully documented parameter, the description is nearly self-sufficient — it tells the agent what the call returns. Only the absence of any failure-mode or id-provenance guidance keeps it from being fully 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% and the single parameter carries its own description ('The reservation (booking) id.'), so the schema does the heavy lifting. The description's 'by id' reinforces the lookup key but adds no format, type, 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 (Fetch) and resource (one reservation) scoped by id, and enumerates the returned payload (guest, dates, check-in/out times, channel, price, prepayment/deposit status, guest-app URL). The word 'one' plus 'by id' cleanly separates it from smoobu_list_reservations without needing the sibling's 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 'by id' phrasing implies the caller must already hold a reservation id, which is useful context, but the description never states when to prefer this over smoobu_list_reservations or smoobu_get_reservation_placeholders, nor any prerequisites. Usage is inferable rather than explicit.

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

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

The readOnlyHint annotation already establishes the safety profile. The description adds the useful detail that these are values Smoobu *would substitute* (i.e. computed, not stored raw) and cites the underlying endpoint, but says nothing about response shape, size, or whether placeholders can be empty for a reservation lacking certain data.

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

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

Front-loads what is returned, then the use case, then the endpoint in one compact block. The enumeration is long-ish but each item conveys concrete return content rather than 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 does the work of telling the agent what comes back by listing placeholder categories, which is the key missing structured information. Complete enough for a simple one-parameter read tool, though it does not describe the key/value shape of the response.

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 there is a single, self-describing parameter, so the schema carries the meaning. The description adds no syntax or format detail about reservation_id, which is the correct baseline when the schema does the work.

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

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

States a specific verb (get) and resource (a reservation's message placeholder values), and enumerates the actual content (guest name, dates, nights, price, check-in link, door PINs). This clearly distinguishes it from siblings like smoobu_list_custom_placeholders and smoobu_list_reservation_messages.

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?

"Useful for drafting a guest message" implies the intended context, but there is no explicit when-to-use vs. when-not, and no sibling is named as an alternative. The agent must infer that this is the read-only lookup tool rather than the send or list tools.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: it is a cheap call, it confirms credentials work, and its id doubles as the customerId consumed by availability checks.

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 clauses, front-loaded with the core action and return fields, followed by usage hint and raw 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?

With no parameters and no output schema, the description compensates by listing the return fields (id, name, email) and the cross-tool significance of the id. Nothing essential is missing for correct invocation.

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

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

The tool takes zero parameters, so there is nothing to misinterpret; the baseline for a no-param tool is 4.

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 (the Smoobu user these credentials belong to), and even enumerates the returned fields (id, name, email). It distinguishes itself from the many list/get siblings by tying the id to availability checks.

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 when to reach for it ('a cheap way to confirm the setup works'), which implies credential/setup validation. It does not name an explicit alternative or exclusion, 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 establish readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the underlying API mapping (GET /api/addons[/{apartmentId}]) and the interpretation legend for calculation type (0/1/2/3), which an agent could not infer from the schema. It stops short of mentioning pagination or rate limits.

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

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

A single dense sentence that front-loads the resource, then the returned fields, then the optional filter and API mapping. The parenthetical example list and enum legend cost little and add value; the trailing endpoint note is the only mildly expendable 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?

With no output schema, the description carries the burden of describing return values, and it does: amount, tax, calculation type, and applicable properties. Combined with the 100%-documented input schema and readOnly annotation, an agent has enough to call it correctly; pagination behaviour is the one gap.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Only add-ons for this property.' The description's 'optionally for one property' largely restates that, so the baseline of 3 applies with no meaningful added syntax or format detail.

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

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

States a specific verb (List) and resource (bookable add-ons) with concrete examples (towels, breakfast, late check-out) and enumerates the returned fields. No sibling tool covers add-ons, so the resource alone differentiates it from the list_apartments/list_price_elements family.

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?

Offers some guidance via 'optionally for one property', which implies the no-argument call returns all add-ons and the argument narrows to one property. However, there are no explicit when-to-use/when-not statements, no prerequisites, and no named alternatives among 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 the underlying call (GET /api/apartments) and what comes back (id and name), which is meaningful since there is no output schema. It omits pagination behavior and result-size expectations for an account-wide listing.

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 plus an endpoint reference; the scope statement and the terminology clarification are front-loaded before the practical 'start here' hint. No sentence is padding.

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

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

For a zero-parameter read-only list with no output schema, the description supplies the two things an agent would otherwise guess: the response fields (id, name) and the endpoint. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond that.

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 every property') and immediately resolves the terminology mismatch by noting Smoobu calls them apartments, which matters because siblings like smoobu_get_apartment use the other word. An agent can tell this apart from the single-apartment getter without opening any schema.

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

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

'Start here to get apartment ids' gives a clear use-case and positions the tool as the entry point for id discovery. It never explicitly excludes the alternative (smoobu_get_apartment) or states when-not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds useful context by naming the underlying endpoint (GET /api/custom-placeholders) and the returned fields, but says nothing about pagination, auth requirements, or result size.

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

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

Two tight sentences: the purpose and returned fields come first, and the API mapping is relegated to a short trailing clause. No filler or redundancy.

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

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

For a zero-parameter read-only list tool with annotation coverage and no output schema, the description does the important work of naming the returned fields. It is nearly complete, missing only return-shape nuances like ordering or pagination behavior.

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, which is the baseline-4 case. Schema coverage is 100% but empty, so there is nothing for the description to clarify beyond the field list it already provides.

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

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

States a specific verb ('List') and resource ('the account's custom message placeholders') and enumerates the returned fields. The account-level scoping implicitly separates it from the reservation-scoped sibling smoobu_get_reservation_placeholders, but 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?

The description gives no when-to-use guidance, no prerequisites, and no reference to alternatives such as smoobu_get_reservation_placeholders. Usage is only loosely implied by the 'List' verb.

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

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

Annotations already declare readOnlyHint=true, so safety is covered by structured data. The description usefully discloses the returned field set and the underlying endpoint (GET /api/guests), but says nothing about pagination behavior, result caps, or ordering — relevant for a list endpoint with page/page_size params.

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

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

A single dense sentence leads with the action and returned fields, followed by the endpoint reference. No filler, though the trailing 'Smoobu: GET /api/guests' is largely redundant with 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 no-required-param list tool with no output schema, the description's field enumeration is the only place the agent learns what comes back, which is valuable. Pagination semantics are the one notable gap, but the schema covers those parameters.

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, query, and page_size are already documented in the schema. The phrase 'optionally search' loosely gestures at the query parameter but adds no format or syntax detail beyond it; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List guests from the Smoobu CRM') and enumerates what is returned (emails, phone numbers, address, notes, bookings), so the agent knows exactly what the call yields. It does not distinguish itself from the sibling smoobu_get_guest (singular), leaving that differentiation to the naming convention.

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?

'optionally search' implies that a search term is the variation trigger, but there is no explicit when-to-use guidance and no mention of when to prefer smoobu_get_guest for a single record. 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 tells the agent this is a safe read. The description adds useful value in describing the per-thread payload (guest name, property, latest message, unread count), but says nothing about pagination behavior across pages, ordering, or performance characteristics.

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 payload description comes first and the API endpoint reference trails as a compact tag. No filler, nothing redundant.

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

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

There is no output schema, but the description compensates by sketching the return shape (one thread per booking, with unread count). For a three-parameter read-only list tool that is largely sufficient, though pagination semantics remain unstated.

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

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

Schema description coverage is 100%, so all three parameters (page_size, page_number, apartment_ids) are already documented in the schema. The description adds no filter syntax, default values, or interaction 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 (the unified guest inbox / threads), and even enumerates the shape of each thread: guest name, property, latest message, unread count. That is enough to separate it from smoobu_list_reservation_messages, though it never names or contrasts with 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 implied by the resource description (browse the inbox), but there is no explicit when-to-use guidance, no mention of prerequisites, and no pointers to alternatives such as smoobu_list_reservation_messages for a single booking's messages or smoobu_send_message_to_guest to reply.

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 already covered. The description adds that the response carries amounts, tax and currency, which is useful context, but it says nothing about pagination, currency conversion behavior, error cases for missing reservations, or line-item aggregation. A 3 fits given annotations carry the safety burden.

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 verb and scope, followed by the concrete list of returned fields and the underlying API route. No filler or redundancy.

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

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

No output schema exists, so the description carries the return-value burden and does so by listing the breakdown components and their accompanying amounts, tax and currency. It is nearly complete for a single-reservation read; only edge behavior (missing id, empty breakdown) is 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 coverage is 100% and the single parameter is documented as 'The reservation (booking) id.' The description only restates that it operates on one reservation, adding no format or constraint 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 verb and resource ('List the financial breakdown of one reservation') and enumerates exactly what the breakdown contains (base price, cleaning fee, add-ons, discounts, coupons, tax, currency). This clearly distinguishes it from siblings like smoobu_get_reservation or smoobu_list_reservations without needing to open the schema.

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

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

Usage is implied by the phrasing 'of one reservation' - the agent can infer this is the per-reservation financial lookup - but no when-to-use condition, prerequisite, or alternative tool is named. It stops short of routing the agent between this and smoobu_get_reservation.

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 readOnlyHint=true, so the description carries the load and does add value: it discloses pagination and enumerates the shape of each returned message (subject, plain-text and HTML body, type). It does not state page size, ordering, or rate limits, which keeps it short of a full behavioral picture.

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 front-loaded sentences with no filler: the purpose and scope come first, the return shape second, and the REST endpoint mapping last. Every clause conveys usable 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 usefully substitutes by naming the fields each message contains and decoding the type values (1 = inbox/from guest, 2 = outbox/sent), plus the pagination behavior and underlying endpoint. An agent has what it needs to call 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?

Schema description coverage is 100%, so page, reservation_id, and only_related_to_guest are already documented in the schema. The description adds no parameter-level syntax beyond clarifying message 'type' values, which are return fields rather than inputs, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the full conversation for one reservation') plus the scoping constraint 'paginated'. The 'one reservation' scope implicitly separates it from the sibling smoobu_list_message_threads, which spans multiple threads, so an agent can select between them 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?

Usage is implied by the scoping ('for one reservation'), which nudges toward smoobu_list_message_threads when the agent only has a thread reference, but no explicit when-to-use or when-not-to-use guidance is given. No prerequisites or alternative routing are 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 covers the safety profile, but the description adds real behavioral context: results are paginated, they span all channels, and they include guest, dates, channel, price and payment status. It stops short of stating sort order, pagination defaults, or whether a date range is expected.

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 front-loaded with the core action, return fields, and filter families, ending with the API route for mapping. No filler, though the long comma-separated filter list is slightly scannability-poor.

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 17-parameter listing tool with no output schema, the description usefully names the returned fields and flags pagination, which compensates for the absent output schema. It is missing only finer operational detail (default page size, ordering, whether ranges are required).

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

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

Schema description coverage is 100% across all 17 parameters, so the schema already documents each filter's syntax and semantics in detail. The description only summarizes filter categories at a higher level, adding little beyond the schema, which matches 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?

Specific verb (List) + resource (reservations) with explicit scope: 'across all channels (Airbnb, Booking.com, direct, ...)', plus the returned fields and the underlying endpoint. This clearly distinguishes it from the singular smoobu_get_reservation and from other list_* 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?

The description implies usage via its filter enumeration (stay range, arrival, departure, creation/modification date, property), so an agent can infer this is the browse/search tool. However, it never states when to prefer this over smoobu_get_reservation or check_availability, and gives no exclusions or 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?

With only destructiveHint=true in the annotations, the description carries real weight: it discloses the delivery path (booking channel inbox or email), that delivery is IMMEDIATE, and that the message cannot be unsent. That is exactly the behavioral context an agent needs before triggering an irreversible external communication.

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

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

Three tight sentences with the warning and the delivery semantics front-loaded. The trailing REST endpoint reference is mild boilerplate that an agent does not strictly need, but it is compact and does not bury the important content.

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 irreversible send with no output schema and no readOnly/destructive annotations beyond destructiveHint, the description covers the critical gap (irreversibility, channel routing). It is silent on what the call returns (e.g., a message id) and on any permission or channel-availability requirements, which keeps it just short of 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% (subject, message_body with HTML/plain-text note, reservation_id), so the schema already carries the parameter burden and a baseline of 3 applies. The description mentions only 'the text' generically and adds no format, length, or channel-specific constraints beyond what the schema 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 precise verb (send a message), the resource (guest of a reservation), and the destination channel (Airbnb/Booking.com inbox or email). It is trivially distinguishable from the sibling smoobu_send_message_to_host, which targets the opposite recipient.

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 a clear operational precondition — 'confirm the text with the user first' — tied to the irreversibility of the send. It does not explicitly route to alternatives such as smoobu_list_reservation_messages or smoobu_list_message_threads for reviewing a thread before replying, so the guidance is strong but not exhaustive.

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 crucial irreversibility fact ('Cannot be unsent'), which is exactly the kind of behavioral trait an agent needs before sending. It also clarifies the visibility semantics of the internal flag, though it says nothing about rate limits or what the call returns.

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

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

Three short sentences, front-loaded with the core action, then the modifier, then the irreversibility warning, then the API mapping. No wasted words and nothing buried.

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

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

For a four-parameter write tool with no output schema, the description covers the action, the key modifier, and the irreversibility risk. The only minor gap is that it doesn't indicate the shape of the response (e.g., the created message id), though that is not required here.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, making 3 the baseline. The description restates the internal flag's meaning as an 'internal note hidden from the guest' and adds the logging rationale, but adds no 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 (post), resource (message on a reservation's thread), and recipient (the Smoobu user/host), which cleanly distinguishes it from the sibling smoobu_send_message_to_guest. The endpoint reference reinforces exactly what operation is performed.

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

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

Gives a concrete use condition for the internal flag — 'handy for logging' — which tells the agent when that mode is appropriate. It never states when to prefer this over send_message_to_guest or list_message_threads, so there is clear context but no explicit alternatives or 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?

With only destructiveHint annotated, the description adds substantial behavioral context: it pushes to every channel with price sync enabled, changes live prices guests see, is reversible by re-setting old values, and requires an existing price for a minimum-stay-only change. This goes well 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?

Five tight sentences, front-loading the purpose, then side effects, reversibility/alternative, operation constraints, and API endpoint. Every sentence adds necessary information without repetition.

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

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

For a destructive nested-array mutation with no output schema and destructiveHint annotation, the description covers purpose, external side effects, reversibility, read-before-write guidance, parameter requirements, and the endpoint. Nothing critical for correct invocation appears 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 coverage is 100%, so baseline is 3, but the description adds an important parameter constraint not in the schema: each operation needs daily_price, min_length_of_stay, or both, and a minimum stay alone requires an existing price. That meaningfully supplements the nested operations array.

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 (Set), resources (nightly price, minimum stay), and scope (dates on one or more properties), and explicitly names smoobu_get_rates as the read counterpart, so an agent can distinguish it from sibling rate and availability tools.

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

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

Provides clear context for when the tool is used: modifying live guest-facing prices and minimum stays. It directs the agent to read current values first with smoobu_get_rates and notes the operation requirement, but does not enumerate explicit when-not-to-use or alternative update paths beyond that.

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 material context beyond that: only passed fields are sent (partial-update semantics) and dates/property are immutable, which directly affects how safely an agent invokes it. It stops short of covering permissions, error behavior, or side effects of status changes.

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 front-loaded sentences with no filler; the field list, partial-update rule, and immutable-field exclusion are delivered efficiently. The trailing endpoint reference is compact and mildly redundant 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 17-parameter mutation tool with minimal annotations and no output schema, the description covers mutable fields, partial-update behavior, and immutable fields well. It omits permission/auth context and response expectations, which keeps it from being fully 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 every one of the 17 parameters is already documented in the schema. The description groups the fields into categories but adds no syntax, format, or constraint detail beyond what the schema provides, matching 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 (update) and resource (existing reservation) and enumerates the mutable field groups, which is highly specific. It does not explicitly name a sibling tool for comparison, though 'existing' implicitly contrasts with smoobu_create_reservation.

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 exclusion ('Dates and property cannot be changed here') but does not name an alternative tool for those cases or state when to prefer this over create/list/get tools. Usage remains implied rather than explicit.

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