smoobu

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

Annotations already declare readOnlyHint=true, and the description reinforces this ('books nothing') while adding genuinely new behavioral detail: per-property unavailability reasons are returned, and the guest-capacity constraint surfaces as an error reason. Auth/token requirements and rate limits are not covered, 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?

Front-loaded with the primary purpose and the value-add (unavailability reasons) in a single dense sentence, followed by two short clauses. The 'Read-only, books nothing' clause partially restates the readOnlyHint annotation, a minor redundancy, but overall it is tight and earns its space.

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

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

With no output schema, the description carries the burden of explaining returns and does so: total price per property plus reasons for unavailability. Required inputs are clear from the schema. Minor gaps remain around response shape details and any per-property result structure, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters fully (including the customer_id lookup hint and apartment_ids omission semantics). The description adds little parameter-level meaning beyond the implicit scoping (availability for a given arrival/departure pair), 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 (check bookable properties, quote total price) and goes further by describing the negative case with concrete reasons (minimum stay, too many guests, arrival day, lead time). It is clearly distinguishable from siblings like smoobu_create_reservation and smoobu_get_rates.

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 context is implied: 'Read-only, books nothing' signals this is a pre-booking check rather than a write, contrasting implicitly with smoobu_create_reservation. However, no sibling is named and no explicit when/when-not condition is stated, so the agent must infer the workflow placement.

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?

Despite destructiveHint=true already flagging the mutation, the description adds substantial behavior the annotation cannot convey: the reservation SYNCS blocked dates to every connected channel (Airbnb, Booking.com), it fails on overlapping dates, and there is no cancel path in this server. It also warns that required guest fields vary with booking-tool 'Form Content' settings — a non-obvious precondition.

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 short sentences, all load-bearing, with the highest-risk facts (channel sync, overlap failure, no cancel) front-loaded before the conditional field note and endpoint reference. No filler or restatement of the title.

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

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

With 23 params, nested price_elements, a destructive annotation and no output schema, the description covers creation semantics, side effects and failure modes well. It does not state what the call returns (presumably a reservation id needed for subsequent get/update calls), which is the only meaningful gap for a mutation with no output schema.

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

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

Schema coverage is 100%, so parameters are self-documented (including channel_id's default of 70 and the 11 = Blocked channel hint). The description still adds value by framing the 3 required vs. guest-field requirements as configuration-dependent, which the schema alone would mislead an agent about.

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

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

Opens with a specific verb+resource ('Create a reservation (or a blocked period) on a property') and immediately clarifies that the created record behaves like a channel booking, distinguishing it from the read/list siblings. An agent can identify what the tool produces 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?

Gives clear conditions: fails if dates overlap an existing booking, and this server offers no cancel so cancellation must happen in Smoobu. Useful when-not guidance, but it never explicitly points to smoobu_check_availability to pre-validate dates or smoobu_update_reservation for modification, so routing to siblings is left implicit.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context: the underlying GET endpoint and the fields returned. It does not mention error behavior for a missing id, but that is a minor gap for a read-only lookup.

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 plus a compact endpoint reference. Every element adds useful information with no waste or repetition.

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

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

For a simple read-only tool with one fully documented parameter and no output schema, the description is complete: it identifies the resource, lists the returned fields, and gives the API endpoint.

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%: apartment_id is fully documented in the schema. The description reinforces the apartmentId path parameter but adds no syntax or format details beyond what the schema already provides, 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 ('Fetch') and resource ('one property') and enumerates the returned detail categories. The single-property scope implicitly distinguishes it from list_apartments, but it does not name or explicitly differentiate against that sibling.

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 no explicit when-to-use guidance, prerequisites, or comparison to alternatives such as smoobu_list_apartments. The purpose implies a lookup by known id, but no conditions or exclusions 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds non-obvious payload context: the response includes contact details, notes, and every booking the guest has made, which signals a potentially large aggregated result beyond the single guest entity.

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 tight sentence with the action front-loaded, followed by the backing endpoint. No filler 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 a simple single-parameter read with no output schema, the description compensates by enumerating the returned fields. It omits error behavior (e.g. invalid id) and auth requirements, but nothing essential to invoking 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?

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: it explains that guest_id is 'the guestId on a reservation', telling the agent where to source the identifier. This clarifies a genuinely ambiguous id.

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 guest) and scopes it to a single record, which cleanly distinguishes it from the sibling smoobu_list_guests. It also names the returned content, so an agent knows exactly what this retrieves versus a list call.

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 'one guest by id' phrasing implies the usage condition (single-record lookup vs listing), but there is no explicit when-to-use/when-not guidance or a named alternative such as smoobu_list_guests. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by disclosing the shape of the response (nightly price, min LOS, availability per date) and the sentinel convention '0 = not available', which is genuinely non-obvious. It omits limits such as maximum range length or rate limits, so it is good but not exhaustive.

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

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

A single dense sentence front-loads what is returned, followed by a short endpoint reference. Nothing is padded, though the 'Smoobu: GET /api/rates' fragment is implementation detail of limited value to 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?

With no output schema, the description correctly carries the burden of explaining what comes back, including the availability encoding, so an agent can interpret results without guessing. It is complete enough for a read-only lookup, with only edge-case behavior (partial ranges, missing dates) 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%, so date formats and property-id constraints are already documented in the schema. The description adds only the cardinality hint ('one or more properties') and the per-date granularity, which is a marginal gain over the structured fields.

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 (nightly price, minimum length of stay, availability per date) for one or more properties, which is far more informative than the title alone. It does not, however, explicitly distinguish itself from the sibling smoobu_check_availability, leaving an agent to infer the difference.

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

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

No when-to-use guidance is given and no alternative is named. With a close sibling like smoobu_check_availability and smoobu_list_price_elements in the toolset, the agent gets no help deciding which to call for a price/availability question.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description adds real value by spelling out the returned fields (guest, dates, check-in/out times, channel and its reference id, price, prepayment/deposit status, guest-app URL) plus the underlying API endpoint. It stops short of noting behavior on missing/invalid ids, which keeps it from a 5.

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

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

A single front-loaded sentence with the verb/resource first and the return-field inventory folded into the same sentence; no filler. The field list is long but it is load-bearing given there is no output schema.

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

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

With no output schema, the description carries the return-value burden and does so effectively by enumerating the fields returned. What an agent needs to call it correctly is present; only edge-case behavior (not found, auth scope) 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 description coverage is 100% for the single reservation_id parameter, so the schema already documents it — baseline 3 applies. The description only reinforces "by id" and embeds {reservationId} in the endpoint path, adding no format or constraint 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 and resource ("Fetch one reservation by id") and enumerates the payload the agent receives, which cleanly distinguishes it from the sibling smoobu_list_reservations. An agent can tell what this does without opening the schema.

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

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

Usage is implied by "by id" — the agent infers it needs a reservation_id, likely obtained from smoobu_list_reservations — but no alternative is named and no when-to-use/when-not guidance is given. It is minimum viable routing, not 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 real value by disclosing the sensitive contents returned (door PIN codes, online check-in link, balance) that an agent would not otherwise know about from 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?

Two front-loaded sentences followed by the endpoint reference; the enumeration is informative rather than wasteful. Slightly list-heavy but every element earns its place by revealing return contents.

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

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

With no output schema, the description compensates by enumerating the returned placeholder contents, and the annotations cover the safety profile. Complete enough for a single-parameter read tool, though it could note the return structure more explicitly.

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% for the single reservation_id parameter, so the schema carries the semantics. The description only echoes 'for this reservation' and adds no format/syntax detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get every placeholder value... for this reservation') and enumerates the contents (guest name, dates, price/balance, check-in link, door PIN codes). It is distinguishable from siblings like smoobu_list_custom_placeholders or smoobu_get_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?

'Useful for drafting a guest message' gives a clear use-case context, but there is no explicit when-to-use-vs-alternative guidance and no exclusion conditions relative to the siblings that also return reservation/message data.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by flagging the call as cheap (a hint at minimal cost/latency) and by explaining the downstream significance of the returned id as customerId for 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?

Two tight sentences plus the endpoint mapping; the core purpose and the credential-scope qualifier are front-loaded with no filler. Every clause adds 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?

For a zero-parameter read tool with no output schema, the description supplies the missing return information (id, name, email) and explains why the id matters. An agent has everything needed to decide to call it 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 there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The description appropriately spends its space on return semantics instead of inventing parameter guidance.

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 a precisely scoped resource: the user the current credentials belong to, with the returned fields (id, name, email) named inline. 'These credentials belong to' cleanly separates it from smoobu_get_guest, which retrieves third-party guests rather than the authenticated account.

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 case — a cheap way to confirm the setup/credentials work — and explains that the returned id is the customerId consumed by availability checks, which is real routing guidance. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that, the description decodes the calculation_type enum values (0 per booking, 1 per person, 2 per night, 3 per person and night) and names the fields returned, which is meaningful behavioral context for interpreting results. It omits pagination/ordering behavior, keeping it short of a 5.

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

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

One dense sentence that front-loads the resource and its scope, followed by the API route mapping. No filler, though the sentence is packed tightly enough that the calculation_type enumeration competes with the core purpose for attention.

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

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

With no output schema, the description compensates by enumerating the key return fields and their value semantics, and the readOnly annotation covers safety. What's missing is any indication of result volume, ordering, or whether add-ons are returned per property vs globally when apartment_id is omitted.

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 apartment_id parameter is documented in the schema ('Only add-ons for this property'), so the description's parallel phrase 'optionally for one property' adds no new syntax or semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

Specific verb+resource ('List the bookable add-ons') with scope made explicit ('optionally for one property') and the returned fields enumerated (amount, tax, calculation type, applicable properties). It also distinguishes itself from nearby sibling listers such as smoobu_list_price_elements and smoobu_list_custom_placeholders by naming the concrete 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 implies usage via 'optionally for one property', which tells the agent the call can be scoped or left global, but it never states when to reach for this tool versus siblings or any prerequisite (e.g. that an apartment_id must first be obtained). Guidance is 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.

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 GET against /api/apartments and returns id and name, telling the agent what shape of data to expect. It stops short of noting pagination or whether the list is account-scoped in size, hence 4.

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

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

Three compact sentences, each earning its place: purpose, terminology clarification, usage entry point, and the underlying endpoint. The most actionable guidance (start here) 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 compensates by stating the returned fields (id and name). For a zero-parameter read-only listing whose safety is declared by annotations, nothing an agent needs to call 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, which is the baseline-4 case. There are no parameters for the description to clarify, and it correctly implies no filtering is required.

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 every property in the account') and explicitly reconciles the naming ('Smoobu calls them apartments'), which prevents confusion with the sibling smoobu_get_apartment. It also names the returned fields (id and name), so an agent can distinguish this list tool from the single-resource getters.

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?

Says 'Start here to get apartment ids', which gives a clear entry-point condition for using this tool before others. It does not explicitly contrast with smoobu_get_apartment or state when not to use it, so it falls short of the explicit-alternatives 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?

readOnlyHint=true already tells the agent this is a side-effect-free read, so the bar is lower. The description adds the endpoint mapping (GET /api/custom-placeholders) and the scoping of placeholders as global/booking/property, but discloses nothing about pagination, result size, or auth requirements.

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

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

Two tight sentences: the scope/return shape first, the API endpoint second. Zero filler and the most decision-relevant information is front-loaded.

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

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

With no parameters and no output schema, the description does the right thing by enumerating the returned fields (key, default value, global/per-booking/per-property), which is exactly the information a missing output schema would otherwise provide. The only gap is that it does not help an agent rule out the similarly named reservation-placeholder 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies: the schema is empty and the description correctly avoids inventing parameter semantics.

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 the account's custom message placeholders') and even enumerates the returned fields (key, default value, scope). It is clear what the tool does, but it never names or contrasts the easily-confused sibling smoobu_get_reservation_placeholders, leaving the account-wide vs reservation-scoped distinction to inference.

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

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

The word 'account's' implies this is the account-level list rather than a per-reservation one, which is the main usage decision an agent faces here. However, there is no explicit when-to-use statement and no named alternative, so the guidance remains implied rather than 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?

The readOnlyHint=true annotation already establishes this is a safe read, so the description's burden is lower. It adds useful context about the CRM payload and cites the underlying endpoint (GET /api/guests), but says nothing about pagination limits, ordering, or result caps 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?

A single sentence with the resource and returned fields front-loaded, plus the endpoint reference. It is efficient, though the semicolon-joined phrasing is slightly dense.

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

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

With no output schema, the description compensates by naming the fields returned (emails, phone numbers, address, notes, bookings), which is genuinely helpful. Pagination mechanics and total-count behavior are left to the schema, a minor gap.

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

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

Schema description coverage is 100%, so page, page_size, and query are already documented with bounds. The description's "optionally search" reinforces the query parameter's role but adds no syntax, matching rules, or examples 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 (guests) and enumerates the fields returned (emails, phone numbers, address, notes, bookings), which is more than a restatement of the name. It does not distinguish itself from the sibling smoobu_get_guest, leaving the collection-vs-single distinction implicit.

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" hints that the query parameter enables filtering, but there is no when-to-use guidance, no mention of when to prefer smoobu_get_guest for a single record, and no stated prerequisites. An agent must infer usage entirely.

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 as a safe read. The description adds useful context by enumerating the returned fields and citing the underlying endpoint (GET /api/threads), but it says nothing about pagination defaults, ordering, or rate limits, despite three pagination-related parameters.

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 resource and the returned content front-loaded, and the endpoint noted at the end. Nothing is padded or redundant.

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

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

With no output schema, the description helpfully enumerates the thread fields an agent will receive, which compensates for the missing return schema. It falls short only on paging behavior and result ordering.

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_size, page_number and apartment_ids are already documented in the schema. The description adds no filtering or paging syntax beyond what the schema provides, 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?

It uses a specific verb and resource ('List the unified guest inbox') and even describes the result shape: one thread per booking with guest name, property, latest message and unread count. This implicitly separates it from smoobu_list_reservation_messages (per-reservation messages), though it 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?

The 'unified guest inbox' framing implies the overview use case, but there is no explicit when-to-use, when-not-to-use, or reference to the alternatives (smoobu_list_reservation_messages, smoobu_get_guest). An agent must infer the distinction.

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 and the exact set of fields returned, which is useful, but says nothing about permissions, pagination, or error behavior for a missing reservation 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?

Two sentences, zero filler, with the substantive content (what the breakdown contains) front-loaded and the API path relegated to a trailing reference. 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 present, the description does the work of enumerating the returned fields, which is the key missing structured information. It is nearly complete for a simple one-parameter read tool; only the relationship to sibling read tools remains 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% and the single required reservation_id parameter is documented in the schema itself. The description adds no syntax, format, or sourcing guidance 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 (list) and resource (financial breakdown / price elements of one reservation) and enumerates the components returned (base price, cleaning fee, add-ons, discounts, coupons, tax, currency). This clearly distinguishes it from smoobu_get_reservation and smoobu_list_reservations.

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

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

The phrase 'of one reservation' implies the tool is scoped to a single booking, which implicitly routes the agent here for pricing detail rather than the general reservation fetch. However, it never names an alternative tool or states when-not to use it, leaving the choice between this and smoobu_get_reservation 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 covers safety, but the description adds real context beyond annotations: the result is paginated, and each message carries a subject, plain-text and HTML body, plus a type code with its meaning (1=inbox/from guest, 2=outbox/sent). It does not mention auth requirements, page size, or ordering.

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

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

Two tightly packed sentences: the core behavior and pagination come first, then the return shape, then the backing endpoint. Every clause carries information and nothing is repeated.

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 responsibly describes the returned message fields and the type enum, and flags pagination. It stops short of pagination mechanics (page size, total counts), which an agent iterating pages would benefit from knowing.

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

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

Schema description coverage is 100% and the schema already documents page, reservation_id, and only_related_to_guest. The description's 'paginated' phrase loosely maps to page and 'full conversation' to only_related_to_guest, but adds no meaning beyond what the schema fields already state, 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 and resource ('Get the full conversation for one reservation') and scopes it to a single reservation, which distinguishes it from the sibling smoobu_list_message_threads. It also names the underlying API call, leaving no ambiguity about what the tool returns.

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: fetch the message thread once you already have a reservation id. However, it never says when to prefer this over smoobu_list_message_threads or smoobu_get_guest for conversation history, and lists no prerequisites 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context beyond that: results are paginated, span all channels, and include guest, dates, channel, price and payment status, plus the underlying endpoint. It could have noted pagination limits or rate behavior but adds real value.

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, front-loaded with the core action and scope, then filters, then the endpoint. Every clause carries information and nothing is redundant.

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

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

For a 17-parameter tool with no output schema, the description usefully names the returned fields and notes pagination, which compensates for the missing output schema. It does not explain pagination limits or how the various date filters combine, leaving minor 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 every parameter is already documented with format and bounds. The description only groups filters into categories (stay range, arrival, departure, creation/modification, property) without adding syntax or semantics beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (reservations) with scope ('across all channels') and enumerates the returned fields, so an agent distinguishes it from smoobu_get_reservation (singular) by name. It stops short of explicitly naming the sibling it is not, so it is clear but not sibling-differentiated in text.

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

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

The filter list implies when to use it (date/property-scoped listing), and the 'List' vs 'get_reservation' naming hints at the alternative, but there is no explicit when-to-use/when-not statement or named alternative. Usage is inferable rather than 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?

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing that the message is delivered IMMEDIATELY, cannot be unsent, and is routed to the booking channel. This is exactly the irreversibility and side-effect context an agent needs before triggering an irreversible send.

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 plus a REST endpoint reference; the irreversible-delivery warning is front-loaded where it matters. The endpoint citation is mildly redundant with the title and description but small and arguably useful for callers.

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 3-parameter send action with no output schema, the description covers the essentials: what is sent, where it goes, and that it is irreversible. It does not describe what the call returns, but a minimal confirmation response is a reasonable assumption and not a blocking gap.

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

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

Schema description coverage is 100%, so reservation_id, message_body, and subject are already documented in the schema. The description only restates the reservation id via the endpoint path and does not add format or content guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (send a message to the guest of a reservation) and clarifies the delivery channel (Airbnb/Booking.com inbox or email), which distinguishes it from smoobu_send_message_to_host and from the read-only smoobu_list_reservation_messages. An agent can identify the correct tool without opening a schema.

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

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

Gives a clear precondition for use — confirm the text with the user first because the message is delivered immediately and cannot be unsent. It does not explicitly contrast with sibling tools such as send_message_to_host or note when not to use it, but the operative guardrail is stated plainly.

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?

Adds real behavioral context beyond the annotations: the message is irreversible ('Cannot be unsent'), which corroborates the destructiveHint=true, and internal=true changes guest visibility. It does not cover auth requirements, rate limits, or notification side effects, so it is helpful but not exhaustive.

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

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

Three tight sentences, front-loaded with the action and recipient, with the caveat and flag semantics following. The trailing raw endpoint reference is mildly redundant but does not bury the key 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 irreversible write with 100% schema coverage and no output schema, the description supplies recipient, visibility semantics, and irreversibility. Nothing critical is missing, though return/confirmation behavior is 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%, so all four parameters are already documented in the schema. The description only restates the internal flag's meaning with a use-case gloss and says nothing new about subject, message_body format, or reservation_id 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 (Post a message) and resource (a reservation's message thread) plus the recipient (the host), which cleanly separates it from the sibling smoobu_send_message_to_guest. An agent can pick the right tool 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?

Explains a concrete usage scenario — internal=true for a note hidden from the guest, described as 'handy for logging' — which tells the agent when the flag matters. It never names an alternative tool or an explicit when-not, so it stops just 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 only give destructiveHint=true; the description adds substantial context: changes propagate to every channel with price sync enabled, affect live prices guests see, and are reversible only by re-setting prior values. It also notes a minimum stay alone requires an existing price, which is behavior not captured by the annotations or 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?

Four compact sentences, each carrying distinct payload (effect, blast radius, reversal, per-operation requirement) with the live-price warning front-loaded. No filler or repetition.

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

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

For a mutation tool with minimal annotations and no output schema, the description covers consequence, reversibility, prerequisite read, and parameter invariants — everything needed to invoke it safely and correctly.

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

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

Schema coverage is 100%, but the description adds a genuine cross-parameter constraint the schema does not enforce: each operation needs daily_price, min_length_of_stay, or both, and a minimum stay alone requires a pre-existing price. That is real semantic value beyond the field-level descriptions.

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) and resources (nightly price, minimum length of stay) scoped to dates on one or more properties. It names the sibling it pairs with (smoobu_get_rates) so an agent can separate it from the read-side tool without opening a schema.

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

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

Explicitly says to read current values with smoobu_get_rates first, and explains how to revert (set the old values again). The condition for using it — changing live prices pushed to channels — is stated directly, leaving nothing to inference.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden and delivers meaningful behavior: partial-update semantics (unsent fields untouched), scope limits (no dates/property), and the underlying PUT endpoint. It omits permission requirements and error/response behavior, keeping it below a 5.

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

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

Three tight sentences, front-loaded with the action and the mutable field set, then the patch rule and the exclusion, ending with the API reference. No filler.

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

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

For a 17-parameter mutation tool with no output schema and minimal annotations, the description covers mutability scope, patch semantics, and exclusions adequately. It could still say more about side effects or validation failures, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so all 17 parameters including status enums and HH:mm patterns are already documented. The description's field grouping adds mild orientation but no syntax or format detail beyond the schema, 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+resource ('Update an existing reservation') and enumerates the mutable field groups (times, guest contact, notes, counts, language, money/paid status), which cleanly separates it from smoobu_create_reservation and smoobu_get_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?

Gives clear usage context: 'Only the fields you pass are sent' clarifies patch semantics, and 'Dates and property cannot be changed here' states an explicit exclusion. It stops short of naming an alternative tool for date/property changes, so it is not a full when/when-not routing prescription.

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