HotelRunner MCP by usefulapi

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description adds genuine operational context on top: a 250 requests/day and 5/minute quota, the underlying lookup window limit, and the from_date workaround. This is exactly the kind of cost/limit disclosure an agent needs before calling.

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, front-loaded with the resource and identifiers before limits and rate cost. Every clause carries information the agent cannot get from schema or annotations.

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 record's contents (rooms, daily prices, extras, payments, guest/billing details, next_states). Combined with quota and lookup-window caveats, nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning: it explains that reservation_number takes either the hr_number form or the channel's code, and that from_date exists to reach past a lookup window. It does not restate formats already in the schema.

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

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

States a specific verb and resource ('One reservation') and names both identifier forms accepted (HotelRunner hr_number or the channel's own code), plus enumerates the payload. It is distinguishable from hotelrunner_list_reservations by its singular scope, 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?

Gives a concrete conditional rule that matters: if the reservation predates HotelRunner's lookup window, pass from_date. It stops short of routing the agent between this tool, list_reservations, and get_transaction_details, so no explicit exclusions or alternatives 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 cover the safety profile (readOnlyHint, non-destructive), and the description adds genuinely useful context beyond them: the response shape (succeeded/failed/in-progress counts, per-channel state, error messages) and the rate budget (250 requests/day, 5/minute) that constrains polling. What's missing is guidance on how long states persist or when polling becomes pointless.

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 tightly packed sentences with zero filler: what it reports, where the input comes from, what it costs, and the endpoint. The most important fact (per-channel status) 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 carries the return-value burden and does so by naming the counts, per-channel state, and error message. The endpoint and rate limit round out a call-ready picture; only polling/retention semantics are absent.

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

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

Schema coverage is 100% and the single parameter is documented there, so the baseline is 3. The description earns above baseline by specifying the exact provenance of transaction_id — the reply from hotelrunner_update_room_calendar — which the schema only loosely hints at as 'an update reply'.

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 (retrieve per-channel status of a calendar update) and immediately names the sibling that produces the input, hotelrunner_update_room_calendar. An agent can distinguish this from the update tool and from unrelated list tools 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 condition for use is explicit: pass the transaction_id returned by hotelrunner_update_room_calendar, so the tool is clearly the follow-up to a calendar write. It does not state whether the agent should poll until a terminal state or how long a transaction_id remains queryable, which leaves one gap.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuinely new operational context: the quota cost of 250 requests/day and 5/minute, plus the underlying endpoint. It does not mention caching or whether the list is static, which would be a natural next detail.

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

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

Three short sentences, front-loaded with what is returned, then the hard rate limit, then the endpoint. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description correctly compensates by describing the returned fields and giving example values, and it documents cost constraints for a quota-limited API. The only gap is a missing explicit contrast with hotelrunner_list_connected_channels, which sits right next to it among siblings.

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. The description usefully explains the semantics of the returned code field and where that value is consumed elsewhere, but there is no parameter surface to add meaning to.

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 all sales channels HotelRunner supports) and describes the content of the result: name and code, with concrete examples (bookingcom, expedia, hrs, online). An agent immediately knows this is a static reference/enumeration endpoint, not a property-specific connection listing.

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 the returned code is the value that hotelrunner_update_room_calendar expects in channel_codes, which gives a clear downstream use case and selects it over the sibling update tool. It stops short of naming hotelrunner_list_connected_channels as the alternative for a property's actual connected channels, leaving that distinction 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 declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact API endpoint and the rate-limit cost (counts as one of 250 requests/day, 5/minute), which materially affects call planning.

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: the first front-loads what is returned, the second carries quota and endpoint. No waste or redundancy.

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

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

With no output schema, the description compensates by describing the returned fields (in-progress, succeeded, failed counts) and the rate-limit and endpoint details. The only real gap is not distinguishing this tool from the similarly named sibling.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. Schema coverage is 100% and the empty object schema matches the description's implied no-argument call.

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 the specific resource (the property's connected channels) and what each entry carries (in-progress, succeeded, failed calendar update counts). The listing verb is only implied, and it never clarifies how it differs from the sibling hotelrunner_list_channels, which is an obvious point of confusion.

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 only implied: it is the endpoint to hit when you need connection status plus sync counts. It gives no when/when-not guidance and no explicit routing against hotelrunner_list_channels, so the 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?

Far beyond annotations, it discloses that the tool sets undelivered=false so reading doesn't depend on a PMS fetch, that results are newest-first, the 30-day retention ceiling, and the 250/day and 5/minute rate limits. It even names the underlying endpoint (GET /api/v2/apps/reservations), so the agent knows this is a read-only HTTP call with real quota cost.

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?

Purpose and scope are front-loaded, and the 'Reply:' and endpoint clauses are compact. It is a dense single block, though, with the rate-limit caveat trailing at the end, which costs a little scannability rather than wasting words.

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 reply fields (items, count, page, pages, next_page) and what summary vs full records include. Combined with the date-window and quota notes, an agent has everything needed to call this tool correctly on the first try.

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

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

Schema coverage is 100%, so the schema already carries the parameter docs and 3 would be the baseline. The description still adds genuine meaning: from_date is the creation date (not an arbitrary filter), the default 10-day and 30-day ceilings, what 'summary' actually contains, and the implicit undelivered=false flag. The page/booked/modified parameters 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 opens with a concrete verb and resource ('List reservations of the property') and immediately scopes it (new, modified, canceled; newest first; 1-50 per page). That framing separates it cleanly from the singular sibling hotelrunner_get_reservation and from state-mutating siblings like update_reservation_state.

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 explains the choice between from_date (creation date, max 30 days back, default 10) and from_last_update_date (changed since), and when to pick detail 'summary' vs 'full'. It also states pagination via next_page. What it lacks is an explicit pointer to get_reservation for a single record, so sibling routing 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, openWorldHint=true, and destructiveHint=false. The description adds important operational context beyond annotations: the request quota (250/day, 5/minute) and the REST endpoint, both of which affect agent behavior.

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

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

The description is front-loaded with the core purpose and returned fields, followed by the key downstream usage, rate limit, and endpoint. Every sentence carries operational value 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?

Despite no output schema, the description enumerates the important returned data and explains how to use inv_code with the update tool. The rate limit and endpoint complete the operational picture for a zero-parameter read-only 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 has zero parameters, so the baseline is 4. The description does not need to explain parameter meanings, and it instead focuses on returned codes and 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: list the property's room types and rates. It also enumerates the key returned fields (inv_code, rate_code, capacity, pricing type, channel codes, updateability), making the tool's scope unambiguous against sibling tools like list_channels or 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 by saying to use the inv_code with hotelrunner_update_room_calendar, which connects this list operation to a downstream mutation workflow. It does not explicitly state when not to use it or compare with alternatives, but the intended role is evident.

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?

Goes well beyond the annotations: says cancel is irreversible and releases the room, that HotelRunner may notify the guest or the OTA channel, that a missing precondition yields state_change_is_not_available, and that the call consumes the property's 250/day and 5/min quota. The annotations (destructive, openWorld, non-idempotent) are consistent with and reinforced by this text.

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 'WRITE:' and the state machine, then consequences, then preconditions, then quota and endpoint — every clause carries load. It is a single dense block, though, and the quota/endpoint tail slightly dilutes scannability of the critical safety warning.

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

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

No output schema exists, yet the description covers the success path, the specific failure code, quota cost, HTTP endpoint, and irreversibility. For a destructive two-event state transition, nothing an agent needs to decide or call safely 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 coverage is 100%, so the baseline is 3, but the description adds the conditional requirement logic (cancel_reason is required only for cancel, confirm=true must be passed to gate a cancel) and enumerates the allowed reasons inline, which the schema only lists without context. The hr_number format itself is left to the schema, keeping it from a 5.

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 ('move ONE reservation to the next state') and enumerates the only two events, 'confirm' and 'cancel', with a one-line gloss of each. This clearly separates it from read siblings like hotelrunner_get_reservation and from the unrelated hotelrunner_update_room_calendar.

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 explicit preconditions (requires_response must be true and the event must be in next_states, checkable via hotelrunner_get_reservation) and an explicit when-not ('only cancel when the user clearly asked for it'). It also names the alternative tool for the precondition check, which is exactly the routing an agent needs.

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 substantial context beyond annotations: this is live inventory pushed to all connected channels, it affects what guests can book and pay, changes are partial by design, and results are asynchronous with a transaction_id. These details are critical for a destructive write operation and are consistent with destructiveHint=true.

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 write action and core scope, then adds constraints and operational warnings in a dense but purposeful paragraph. Every sentence mostly earns its place, though the description is long and could be more scannable with structure.

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

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

For a complex destructive live-inventory mutation with no output schema, it covers prerequisites, partial-update behavior, channel propagation, async transaction handling, rate limits, and result-checking follow-up. An agent has enough information to use it correctly without opening other documentation.

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 parameter-level descriptions are already strong. The description adds useful cross-parameter semantics: the 90-day maximum range, one-room-type constraint, optional weekday/channel scoping, and the requirement that room update flags be enabled before certain changes are accepted.

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: change availability, price, min/max stay, stop-sale, CTA/CTD for one room type over a date range. Scope is sharply bounded to one inv_code, up to 90 days, optional weekdays and channels, which clearly distinguishes this from sibling 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?

Gives strong operational conditions: only fields passed are changed, one change per call, no full refresh, and only rooms with the relevant update flag enabled can accept the change. It also points to hotelrunner_list_rooms for prerequisites and hotelrunner_get_transaction_details for async results, though it does not explicitly name alternative tools for other workflows.

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