Beds24 MCP by usefulapi

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

Annotations supply only destructiveHint, and the description goes well beyond that: it discloses side effects (immediately blocks inventory, synced to connected channels), reversibility (cancel via update_booking), and an auth prerequisite (token with bookings write access). This is exactly the behavioral context an agent needs before mutating shared inventory.

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 flows through options, undo, and auth requirement. Every sentence carries new information; nothing restates the name or title.

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

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

For a 34-parameter mutation tool with no output schema, the description covers behavior, side effects, auth, and undo well. It omits what a successful call returns (e.g. the created booking id), and only briefly touches the large optional-field surface, so it is strong but not 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 coverage is 62%, so the schema already documents most fields. The description adds meaning for checkAvailability and the notify flags, but it does not touch the three required parameters (roomId, arrival, departure) or the many other optional fields. With the schema doing the heavy lifting, 3 is the correct baseline.

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 with scope: 'Create a new booking in a room for given dates and guest details.' It also names beds24_update_booking as the tool for undoing the operation, which disambiguates it from the sibling update tool and lets an agent place it correctly in the create/update/get/list 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?

Provides clear operational context: when to set checkAvailability=true (refuse if room not free), notifyGuest/notifyHost for emails, and the explicit undo path via status cancelled with beds24_update_booking. It lacks any explicit 'when not to use this' statement, so it stops short of full 5-level 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral value: the exact composed payload (invoice items, info items, additional guests) and the fact that cancelled bookings are still returned. It does not discuss rate limits or error behavior, but for a read-only getter this is solid added context.

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

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

Three short sentences, no filler: what is fetched, what it includes, the status caveat, and the underlying endpoint. Front-loaded with the core purpose.

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-parameter read with no output schema, the description compensates by enumerating the returned components and status coverage, so an agent knows exactly what to expect without a response 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents bookingId including its positive-integer constraint. The description adds nothing about the id format or source, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (one booking by id) and enumerates the payload it returns (invoice items, info items, additional guests). This clearly separates it from beds24_list_bookings and beds24_get_unit_bookings.

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

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

The phrase 'one booking by id' implies the single-record lookup case versus the list siblings, and 'Works for any status, including cancelled' removes a common pre-call doubt. It stops short of explicitly naming an alternative tool or stating exclusions, so it is clear context rather than 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?

readOnlyHint=true already establishes the safety profile, so the description's added value is disclosing the return shape (per-date true/false) and the endpoint mapping — genuinely useful given there is no output schema. It omits pagination behavior even though a page parameter exists.

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 most load-bearing fact (the endDate convention) front and center. The endpoint-string sentence is mildly redundant but costs almost nothing.

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 well to state the boolean-per-date return. But it says nothing about pagination or how the mix of optional filter parameters (dates, roomIds, propertyIds) behaves when omitted, which matters for a 5-parameter, 0-required tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented. The description restates the endDate/last-night convention without adding format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource+output form: per-date boolean availability for rooms across a night range, and even names the backing endpoint. It does not, however, differentiate itself from close siblings such as beds24_get_room_calendar or beds24_get_room_offers, so an agent must infer the boundary.

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

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

No when-to-use guidance, no conditions for choosing this over get_room_calendar or get_room_offers, and no note on how the optional filters (roomIds vs propertyIds) should be combined. The endDate clarification is a parameter detail, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the include-flag mechanism and the specific default projection (numAvail, minStay, maxStay, override, prices) applied when no flags are set, which directly affects what an agent receives back. It does not discuss pagination behavior, though the schema covers that via the page parameter.

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 returned resource and its fields before the include-flag mechanics. Dense but every clause carries information; the API endpoint citation is slightly expendable.

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 largely meets it by naming the returned field families and their date-range shape. Pagination and the pages.nextPageExists signal live in the schema rather than the description, and per-flag semantics remain thin, so it is not 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 coverage is only 46%, and the seven include* flags (includePrices, includeMaxStay, includeMinStay, includeNumAvail, includeOverride, includeMultiplier, includeLinkedPrices) carry no schema descriptions. The description compensates by explaining what include flags do collectively and which fields the default set yields, plus what price1..price16 represent. It stops short of defining each flag individually.

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

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

States a specific verb and resource ('Per-day calendar values for rooms') and enumerates the exact data returned: units available, min/max stay, multiplier, override, and price1..price16 as date ranges. This lets an agent distinguish it from beds24_update_room_calendar (write) and beds24_get_room_availability without opening either schema.

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

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

The description explains the include-flag selection mechanism and the fallback default set when no flags are given, which is genuine usage guidance. However, it never states when to prefer this tool over siblings like beds24_get_room_availability or beds24_get_room_offers, so the routing guidance 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?

The readOnlyHint annotation already declares this is a safe read, so the bar is lower; the description adds real context by disclosing the response contents (total price, units available) despite there being no output schema, and by establishing the pre-booking sequencing. It does not mention pagination behaviour, though the page parameter's own schema text covers that.

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

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

Two short sentences front-load the purpose and return shape, then the usage rule, with the endpoint reference appended as a compact traceability note. No sentence is wasted 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?

For a 10-parameter tool with no output schema, the description covers the core quote path but omits how the filter parameters affect scope and does not mention that results may be paged. Those gaps are recoverable from the schema text, leaving it adequate but not complete.

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

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

Schema coverage is 80%, so the schema already documents most parameters; the description only adds the high-level meaning 'given dates and guests', which maps to arrival/departure/numAdults. It says nothing about the scoping parameters (roomIds, offerIds, propertyIds) that let an agent narrow a quote.

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 ('Quote a stay') and enumerates what is returned — bookable offers with total price and units available — which is more informative than a generic 'get offers'. It stops short of explicitly naming how it differs from the close sibling beds24_get_room_availability, so it is clear but not fully differentiated.

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

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

'Use before creating a booking' gives a concrete workflow context and implicitly points at the downstream sibling beds24_create_booking. There is no explicit when-not or alternative condition (e.g. when to prefer get_room_availability or list_fixed_prices instead), 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?

Beyond readOnlyHint=true, it discloses a non-obvious failure mode: Beds24 returns HTTP 200 with validToken=false for a bad token, so callers must inspect the body rather than trust the status code. That is exactly the kind of behavioral quirk annotations cannot express.

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

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

Three tight sentences: capability first, usage second, gotcha third. Each sentence carries distinct information and none is redundant.

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

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

With no input params and no output schema, the description covers everything an agent needs: what is checked, what comes back, when to use it, and the HTTP-200 gotcha. Nothing material 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 the baseline is 4; there is no parameter syntax that could be misunderstood. The description also lists the response fields, which compensates for the absence of an output 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 (check) and resource (the configured Beds24 token) and enumerates exactly what is surfaced: validity, scopes, owner id, expiry, and property restriction. This is unambiguous and clearly distinct from the booking/room/review 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?

"A cheap way to confirm setup and see which scopes are granted" gives clear context for when to reach for this tool. It does not name alternatives or exclusions, but none of the siblings cover token/auth validation, so the routing is essentially unambiguous without them.

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 readOnlyHint=true, so the description earns credit for adding the 'Beta' status warning (a stability/behavioral risk not in structured data) and clarifying endDate semantics. It stops short of describing pagination or result-size behavior, which the schema only partially covers, 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 terse fragments with the core purpose front-loaded first, followed by the one semantic nuance and the source endpoint. Nothing is padded and every clause carries signal.

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 characterizes the return as a date-keyed occupancy grid, which is what an agent most needs to interpret results. It leaves pagination and the interaction of roomIds vs propertyIds to the schema, which handles them, so the definition is nearly complete for this tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, and the description's 'endDate is the last night' simply restates the schema's 'Last night' text. It adds no new syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb+resource outcome — 'Which units of each room type are booked on each date' — and clarifies the shape as an 'occupancy grid keyed by date,' which is more concrete than the title alone. It does not, however, explicitly distinguish itself from siblings like get_room_availability or get_room_calendar, so an agent must 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?

There is no when-to-use or when-not guidance, and no alternative sibling is named despite several overlapping date/room tools (get_room_availability, get_room_calendar). The Beta note is a stability caveat rather than usage direction, so an agent gets no routing help.

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

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

Annotations already declare readOnlyHint=true, but the description adds real behavioral context beyond them: a hard 100-per-call cap, the Beta status of the endpoint, and the underlying Beds24 API path. It does not say whether more than 100 reviews exist or how to page past the cap, so it stops short of 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 compact sentences, front-loaded with the resource and content, followed by the cap and the Beta/endpoint metadata. No filler or repetition of the title.

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

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

For a read-only, single-parameter tool with no output schema, the description covers the return contents, the row cap and the Beta caveat, which is close to sufficient. It leaves open how to retrieve reviews beyond the 100 cap or whether results are ordered by date, a minor gap for a one-parameter list 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% and the single roomId parameter is fully documented in the schema (Beds24 room id linked to the Airbnb listing). The description adds only the phrase 'for one room', so it neither compensates for nor extends the schema meaningfully — baseline 3.

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

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

States a specific verb (List) and resource (Airbnb guest reviews for one room), then enumerates the returned content types (ratings, public review, private feedback, host response), which cleanly distinguishes it from the sibling beds24_list_booking_com_reviews.

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: the agent can infer you call it with a roomId to fetch that room's Airbnb reviews. There is no explicit statement of when to prefer it over the Booking.com counterpart or which room states produce results, leaving selection to inference.

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

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

Annotations already cover the read-only safety profile, yet the description adds two useful operational facts: a hard cap of 100 results per call and the warning that Beds24 flags the endpoint Alpha. It also discloses the upstream mapping (GET /channels/booking/reviews), giving the agent traceability. It does not say what happens when more than 100 reviews exist, so pagination behavior remains unclear.

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 contents in one compact sentence, followed by the limit and the Alpha caveat. The trailing 'Beds24: GET /channels/booking/reviews' is metadata useful for traceability but not for tool selection, making it slightly less than 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?

With no output schema, the description compensates by enumerating the return fields (scores, content, reviewer, reply) and the 100-item ceiling, which is enough for an agent to call it correctly. It stops short of explaining what to do beyond the 100-result limit, the one remaining gap for a list 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% and both parameters are already documented with pattern and range constraints. The description only restates the 'on or after this date' semantics of 'from' and adds nothing about property ID or date formatting beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Guest reviews from Booking.com for one property') plus the date filter and the returned fields (scores, content, reviewer, reply). The Booking.com qualifier implicitly separates it from the sibling beds24_list_airbnb_reviews 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 conditions (one property, reviews on/after a date) imply when the tool applies, but it never names an alternative or an exclusion — e.g. that this is Booking.com-only and beds24_list_airbnb_reviews should be used for Airbnb. 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 carry readOnlyHint=true, so the description has to add real behavior and it does: an OAuth scope requirement (bookings-financial) and an Alpha stability caveat, both of which materially affect whether and how the agent calls it. It stops short of describing pagination behavior or the response envelope, but that is a reasonable omission.

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

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

Three short sentences, each doing distinct work: what is returned, the auth/lifecycle constraints, and the underlying REST endpoint for traceability. Purpose is front-loaded and there is 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?

With no output schema, the description adequately conveys the return shape (invoices plus charge and payment line items) and the access requirement. The only gap is pagination/response-envelope behavior, though the 'page' parameter's own description already points at pages.nextPageExists.

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% - both 'page' (with nextPageExists guidance) and 'bookingIds' are fully documented in the schema. The description only implies a booking-scoped listing ('for bookings') and adds no syntax, batched-limit, or paging meaning beyond what the schema already states, 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?

Specific verb (List) plus resource (invoices) and it goes further by naming the sub-resource returned: line items (charges and payments) for bookings. That is more precise than a bare 'list invoices'. It does not explicitly contrast itself with any sibling tool (e.g. beds24_list_bookings), though no sibling covers invoices, so the risk of mis-selection is low.

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

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

It supplies two real preconditions - the bookings-financial scope and the fact that Beds24 flags the endpoint as Alpha - which tell an agent when the call will succeed and how much to trust it. However, there is no statement of when to reach for this tool versus producing invoice data another way, nor any exclusion. Usage is implied rather than prescribed.

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 genuine context beyond the schema by naming the channels messages come from (Airbnb, Booking.com, Vrbo, direct), but says nothing about pagination behavior, result volume, or permissions.

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

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

Two dense sentences with the core action and filter surface front-loaded; the trailing raw endpoint reference (Beds24: GET /bookings/messages) is low-value but brief. Little waste overall.

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

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

For a read-only list tool with 89% schema coverage and no output schema, the description covers the filter surface and message scope adequately. It could note the paginated response shape, but the page parameter description already handles that.

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

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

Schema description coverage is 89%, so the schema already documents most parameters. The description restates the filter dimensions (booking, property, room, read/unread, source, age) but omits masterIds, messageIds and page, adding no syntax or format detail beyond 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 and resource (read the guest conversation on bookings) and enumerates the message categories it returns (guest, host replies, internal notes, system). This clearly separates it from siblings like beds24_send_booking_message and beds24_mark_messages_read without opening any schema.

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

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

The description implies usage by listing filterable dimensions, but never states when to choose this tool versus alternatives such as beds24_get_booking or beds24_list_bookings. No exclusions or prerequisites are given, so the agent must infer context.

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

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

Beyond the readOnlyHint annotation, the description discloses the important default behavior (no filters -> upcoming bookings only) and the authorization scopes required for guest data (bookings-personal) and invoice items (bookings-financial). It does not describe pagination behavior or result shape, though the `page` parameter schema partly covers paging.

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 search scope, then default behavior, then filter shortcuts, then scopes. Dense but every sentence contributes information; the single long opening clause is slightly heavy to parse 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 24-param, zero-required listing tool with no output schema and minimal annotations, the description covers the queryable surface, default no-filter behavior, and permission requirements well. It lacks any note on result format/completeness or how paging interacts with large result sets, which is the main remaining 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?

With 83% schema coverage the baseline is 3, but the description adds real meaning where the schema does not: the `filter` enum values are undefined in the schema yet fully explained in the description, and the scopes tied to includeGuests/includeInvoiceItems are clarified. Remaining params (includeInfoItems, includeBookingGroup) are left to the schema.

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

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

The description gives a specific verb+resource ("Search bookings") and enumerates the exact dimensions queryable (arrival/departure range, booking/modified time, property, room, channel, status, free-text), which clearly sets it apart from the single-record beds24_get_booking. It stops short of naming an overlapping sibling such as beds24_get_unit_bookings, so sibling routing is left 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?

Provides clear usage context: no filters returns only upcoming bookings, and each `filter` shortcut is defined with its time window (arrivals, departures, new, current). It does not state when to prefer an alternative tool (e.g. get_booking for a single id) or when-not to use this tool, so the exclusions half of the guideline is missing.

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 bar is lower; the description goes beyond it by enumerating what a rule contains (date span, min/max nights, per-room and per-person prices, discounts, arrival days, channel export), which is valuable given there is no output schema. It omits pagination behavior, though the schema's 'page' description partially covers that.

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

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

Two tightly packed sentences: the field inventory is front-loaded and the endpoint reference is a compact trailing tag. Nothing is wasted and the reader gets the payload shape immediately.

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

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

With no output schema, the description correctly compensates by listing the fields returned, and pagination is handled in the schema. It is close to complete for a read-only listing tool, though it never explains which filters are optional or how the id filters combine.

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 80% (four of five parameters documented, only includeRateCodes bare), so the baseline is 3. The description adds no filter syntax, id format, or interaction notes for roomIds/propertyIds/fixedPriceIds beyond what the schema already says.

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

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

States a specific verb ('List') and resource ('fixed price rules'), with a clarifying gloss ('seasonal rates') that pins down the domain concept, plus the underlying Beds24 endpoint. It does not explicitly distinguish itself from the other list/offer tools, but the resource is specific enough to be selectable.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The description never mentions how this relates to sibling tools such as beds24_get_room_offers, so the agent must infer the context entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description still adds the required auth scope and names the underlying GET /properties endpoint. It stops short of describing pagination behaviour, which the agent must infer from the page parameter.

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: what is listed and returned, then optional flags, then the auth requirement and endpoint. The highest-value information is front-loaded with no filler.

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

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

With 11 optional params and no output schema, the description usefully pre-announces the returned fields and the scope requirement. It leaves paging and id-filtering semantics to the schema, which is a minor gap rather than an omission that would cause a wrong call.

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 73% and the schema documents page, roomIds/propertyIds and the include flags individually. The description categorises five optional include flags (texts, pictures, offers, unit details, all rooms) but says nothing about page, roomIds, propertyIds, includeLanguages, includePriceRules or includeUpsellItems — a baseline 3 with modest added framing.

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 (properties in the account) and enumerates the payload returned — address, currency, check-in times, room types. No sibling covers property listing, so an agent can distinguish it immediately from the booking/room/review 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?

The description gives a prerequisite ("Requires the properties scope") but no explicit when-to-use or when-not-to-use guidance, and no named alternative. Usage is implied by the resource name 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 already flag destructiveHint=true, so the safety profile is partly covered. The description adds useful context that this is a bulk operation ('one or more') and that it can be reversed via read=false, but it discloses nothing about partial failures, ID validation, or permission requirements.

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

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

Two tightly packed sentences, with the core operation and its inverse front-loaded before the API mapping detail. Every clause carries weight.

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 two-parameter mutation with no output schema, the description covers the operation, its inverse, and the underlying endpoint. Only edge-case behavior (invalid IDs, partial success) is left unstated, which is 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 both parameters are already documented in the schema, giving a baseline of 3. The description's '(or unread with read=false)' and implicit batching restate what the schema already says rather than adding new 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 (mark read/unread) and resource (booking messages), and the read=false toggle clarifies the full scope of the operation. It distinguishes itself implicitly from siblings like beds24_list_booking_messages and beds24_send_booking_message, but never names an alternative 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 implies when to use it (after a message has been consumed) and notes the unread toggle, but gives no explicit when-to-use guidance or prerequisites. The use case is self-evident for a state-flag mutation, so implied usage is adequate but not rich.

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 flag destructiveHint=true; the description goes further by explaining *why* it is destructive ('cannot be unsent') and enumerating the delivery channels (Airbnb, Booking.com, Vrbo, email). It still omits auth requirements, rate limits, and failure behavior, so it is strong 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?

Two tight sentences with the default behavior front-loaded and the irreversibility warning attached to the mode it applies to; the trailing endpoint reference is a minor but non-wasteful anchor.

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 destructive mutation with no output schema, the description covers mode semantics, delivery path, and irreversibility. It does not describe what the call returns (e.g., message identifier), which would be the only remaining 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning beyond the schema's terse 'host (to the guest, default) or internalNote (private)' by spelling out channel routing and irreversibility for host mode. bookingId and message get no extra treatment 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 ('Send a message on a booking's conversation') and anchors it with the underlying API route (POST /bookings/messages). It is immediately distinguishable from read-oriented siblings like beds24_list_booking_messages and beds24_mark_messages_read.

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

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

The description explains the two operating modes and their consequences: source=host (default) routes through the guest's channel, while source=internalNote is a private host note. That is genuine when-to-use guidance, though it never names sibling alternatives such as mark_messages_read for handling replies.

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

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

With only destructiveHint=true in annotations, the description carries the burden well: it discloses partial-update semantics, that cancelled status can be reversed by setting status back, that changes sync to channels 'where allowed', and that addInfoItems is additive rather than replacing. Missing are permission/auth requirements and any conflict behavior when dates overlap an existing stay.

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 dense sentences with the scope front-loaded and zero filler; the enumerations earn their place by telling the agent which facets are mutable. Slightly overstuffed in places (the endpoint note and channel-sync clause) but no real waste.

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

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

For a 33-parameter mutation tool with no output schema and only 61% schema description coverage, the description supplies the essential semantics an agent needs: which fields are mutable, that updates are partial, cancellation/reversal via status, and additive info items. It stops short of covering the many unlabeled fields and any error/permission 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?

Schema coverage is 61% across 33 params, so the description must compensate and does: it groups the changeable fields, illustrates the status enum ('confirmed, or cancelled to cancel'), and clarifies that addInfoItems are code/text pairs added on top of existing ones. It still gives no format hints for many covered-only-by-name fields like tax, deposit, or company.

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

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

States a specific verb ('Change an existing booking') and enumerates the changeable resource facets (dates, room/unit, guest counts, details, notes, flag, price, status). It is unambiguous against read-side siblings like beds24_get_booking or beds24_list_bookings, though it never names a sibling to differentiate from beds24_create_booking 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 rather than stated: it is for modifying an existing booking, and 'Only the fields you pass change' is a useful partial-update cue. However there is no explicit when-not guidance, no mention of prerequisites (e.g. needing an existing booking id) and no routing to an alternative such as beds24_create_booking.

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

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

Annotations only declare destructiveHint=true; the description adds real value beyond that with 'These values sync to channels' (external side effect) and the restore workflow for the destructive nature of overwriting. It stops short of stating permissions or rate limits, but meaningfully enriches the safety 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?

Front-loads the verb and scope, then layers fields, the null rule, the sync side effect, and the read-first advice in tight sentences. Every sentence carries information an agent needs; nothing is filler.

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

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

For a 24-parameter mutation tool with no output schema and only a destructiveHint annotation, the description is well covered: it names the settable fields, the external sync effect, the restore workflow, and the API endpoint. It omits auth/permission requirements, which would round it out, but the essentials are present.

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

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

Schema coverage is high at 83%, so the baseline is met by the schema itself, but the description still adds value by grouping the 24 parameters (availability, stay rules, multiplier, override, price1..price16) and restating the null-removes-price semantics for the many price slots. It also helps interpret fields like minStay/maxStay/multiplier that lack schema 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?

Opens with a specific verb and resource ('Set per-day calendar values'), scopes it to ONE room over a date range, and enumerates exactly which fields are settable, including the override enum values. An agent can distinguish this from sibling get_room_calendar and get_room_availability 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 an explicit prerequisite flow: 'Read the current values first with beds24_get_room_calendar so you can restore them,' naming the sibling to use before this destructive operation. It does not spell out a when-not-to-use case, but the read-first guidance and the null-to-remove rule give clear operating context.

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