ThinkReservations MCP by usefulapi

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

readOnlyHint already declares the safety profile, but the description adds real value: it confirms nothing is booked, states the required auth scope 'read:availability', and describes the shape of the pricing breakdown (fees, taxes, deposit, total). It does not cover behavior when no availability exists, but the added context is substantial.

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 payload scope front-loaded and the mutation warning and auth requirement trailing. 'Books nothing' mildly restates readOnlyHint, a small redundancy, but nothing else is wasted.

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

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

With no output schema, the description usefully enumerates the returned fields, and it flags the required scope, which is critical for a scoped API. Minor gaps: no note on how unavailable dates are represented and no occupancy constraint hints, but an agent can call it correctly.

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

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

Schema coverage is 86%, so dates, adult/child defaults and coupon semantics are already documented in the schema. The description adds no parameter-level meaning beyond that, and the one undocumented parameter (number_of_pets) is left unexplained in both places. 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 uses a concrete verb ('Search what the property can sell') tied to a specific resource for a stay, and enumerates the returned payload (rate types, fees, taxes, deposit, total). This differentiates it from rate-type and inventory siblings implicitly via 'price for the whole stay', though no sibling is named explicitly.

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

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

'For a stay' and 'price for the whole stay' imply the whole-stay quoting use case versus nightly rate lookups, but the description never states when to prefer this over thinkreservations_get_daily_rates or get_inventory. No exclusions or prerequisites beyond the scope requirement are given.

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 the useful auth requirement ('Needs scope read:rate') and confirms the data returned, but says nothing about maximum date-range size, rate limits, or behavior for dates without an active rate.

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-loaded with the core purpose and followed by the prerequisite scope. No filler or repetition of the tool name.

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

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

With no output schema, the description usefully enumerates the returned dimensions (price, minimum-stay, CTA). It covers purpose, scope requirement, and output shape; only edge-case behavior for large or invalid date ranges 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 four parameters (including the optional room_type_id filter) are already documented in the schema. The description adds no extra semantic detail such as date ordering rules or whether room_type_id narrows versus aggregates results, 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 ('Get') and a concrete resource with enumerated attributes: day-by-day price, minimum-stay rules, and closed-to-arrival restrictions for one rate type over a date range. This is clearly distinct from siblings like get_rate_type (metadata) or get_availability, though it does not name those siblings 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 by describing the returned data, and adds the required scope 'read:rate' as a precondition. However, it never says when to prefer this over get_availability, get_inventory, or get_rate_type, nor any exclusions or limits.

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 signaling a safe read, the description adds the auth scope requirement, which annotations do not convey. Beyond that it says only 'basic details' without indicating what fields or structure come back, so the disclosure of behavior is thin.

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-loaded with the purpose and followed by the permission requirement. 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?

For a zero-argument, read-only lookup, an agent has enough to invoke it correctly. The one gap is that 'basic details' never gets defined and there is no output schema, so the expected response shape remains unknown.

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 compensate for; schema coverage is 100% and the empty object is self-explanatory. Baseline 4 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 (get) + resource (property/hotel details) with a scope qualifier -- 'the property the API key is bound to' -- that makes clear this is a single-object lookup, not a listing. It implicitly distinguishes it from siblings like list_rooms or get_daily_rates, though it never names them.

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 states the required auth scope ('read:hotel'), which is a real prerequisite for a caller. However, it gives no guidance on when to reach for this versus other endpoints (e.g. when you need room-level vs property-level data), so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the required auth scope ('Needs scope read:availability'), which is real operational context an agent cannot get from annotations — but it says nothing about pagination, empty results, or how missing room_type_id behaves.

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, zero filler, with the resource and scope of the result front-loaded before the auth requirement. Nothing here is redundant with the name.

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

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

No output schema exists, so the description carries the return shape; it does state the key returned value ('units left' per room type), which is the minimum needed. It stops short of describing result structure, date-inclusivity, or behavior when inventory data is absent for a night.

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

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

Schema description coverage is 100%, so all three parameters are already documented with formats and patterns. The phrase 'per room type' hints that room_type_id is an optional narrowing filter and that results are grouped by room type, which is marginal added meaning over 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?

Specific verb ('Get') and resource ('daily inventory (units left) per room type for a date range'), so the operation is unambiguous. However, it does not differentiate itself from the closely related sibling thinkreservations_get_availability, and inventory-vs-availability is exactly the distinction an agent needs to resolve.

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 date-range framing implies when the tool applies, but there is no explicit when-to-use, when-not, or pointer to alternatives such as get_availability. The agent is left to infer the choice between inventory and availability on its own.

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 the auth scope requirement (read:rate) plus the fact that embedded policies are returned with the rate type — context annotations do not carry. It does not discuss behavior for a missing/invalid id, 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?

Two short sentences, zero filler, with the core action front-loaded and the auth requirement appended as a secondary constraint.

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?

One required parameter, no nested objects, no output schema, and readOnlyHint already covers the safety profile — the description says enough to call it correctly. A note on not-found behavior would make it 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 100% and the schema itself explains the id comes from list_rate_types, so the description adds nothing beyond 'by id'. Baseline 3 is appropriate when the schema does the parameter work.

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

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

States a specific verb (Get) and resource (one rate type and its policies) scoped to a single id, which clearly separates it from the list_rate_types sibling that returns many. It stops short of naming the sibling explicitly, so an agent must infer the singular/plural split.

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?

'Needs scope read:rate' gives a concrete prerequisite for calling it. However, there is no explicit statement of when to prefer this over list_rate_types, no error/not-found behavior, and the retrieval-vs-list choice is only implied by the word 'one'.

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 assert readOnlyHint=true, so safety is covered; the description adds the OAuth-style scope requirement and the semantic boundary of what counts as a blackout (room-level, not property-level). It doesn't discuss result shape beyond the id/date pair, but that plus the scope note is meaningfully beyond the annotations.

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: the resource scope comes first and the prerequisite second. Every clause carries information an agent needs to select and call it.

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 2-param read-only list with no output schema, the description compensates by sketching the return shape (room id and date pairs) and the auth scope. Minor gaps remain, such as behavior on empty ranges or any maximum span, but nothing that would cause a mis-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 coverage is 100% and both parameters carry their own descriptions plus date-format patterns, so the schema does the heavy lifting. The description only reasserts that the tool operates over a 'date range' without adding boundary or inclusivity semantics beyond 'First date'/'Last date'.

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 blackouts) and immediately bounds it: 'room-specific blocked dates (room id and date pairs), not whole-property closures.' This negative definition tells an agent exactly what this tool returns versus a broader closure concept, so it's distinguishable 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 a concrete prerequisite ('Needs scope read:availability') and rules out whole-property closures, which is a real usage constraint. It stops short of naming an alternative tool for whole-property closures, so the routing 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, and the description adds genuinely useful context with the required scope read:rate, which an agent cannot get from structured fields. However, it says nothing about whether results are paginated, scoped to a date range, or active/inactive, which matters for a list endpoint with no output schema.

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

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

Two short sentences, purpose first and the auth requirement second, with zero filler. Every sentence carries information the agent needs.

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-param, read-only listing with readOnlyHint annotations, the description covers what it does and what credential scope is needed. The only notable gap is return behavior (pagination, whether inactive promotions are included), which is more than the minimum but short of complete for a tool 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?

The tool takes zero parameters, so the baseline is 4; there is nothing to document and the description correctly doesn't invent parameters. The scope note is an auth concern rather than a parameter, so it does not detract.

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 promotions configured for the property'), which cleanly separates it from siblings like list_rate_types and list_blackouts. It doesn't explicitly name those siblings, but the resource noun alone is distinctive enough.

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

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

Usage is implied by the resource name rather than stated; there is no guidance on when to prefer this over list_rate_types (promotions vs rate types are easily confused) or any prerequisite context. For a zero-param list tool this is minimally viable but leaves a real ambiguity unresolved.

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 cover readOnlyHint, so the description earns credit for adding two things beyond them: the return content ('with their policies') and the required auth scope 'read:rate'. It still says nothing about pagination or result size limits for a list operation.

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-loaded with the operation and its payload, followed by the auth prerequisite. 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 zero-parameter, read-only list with no output schema, the description covers purpose, return content, and the auth scope. That is everything an agent needs before calling it.

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

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

The tool takes zero parameters, which is the baseline-4 case. Nothing about parameters needs explaining here.

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 rate types the property offers', and it adds that policies are included in the response. It does not explicitly distinguish itself from the sibling get_rate_type, but the list-vs-get naming makes the distinction inferable.

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: a reader infers this is the bulk-overview call and get_rate_type is the single-record call. There is no explicit when-to-use/when-not statement or named alternative.

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, the description discloses two things annotations cannot: the required scope read:reservation and the conditional nullability of guest contact fields without read:customer. The "give at least one filter" validation rule is also behavior a caller must know before invoking.

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 sentences in descending order of importance: purpose, filter rule, then scope/permission caveats. Dense and front-loaded, though the mid-sentence filter requirement could be split for scannability.

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 9-param, zero-required list tool with no output schema, the definition covers paging, the filter prerequisite, permission gating and field-level degradation. Missing only sort semantics and what distinguishes a stay-date match from a creation-time match.

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 67% schema coverage, the description adds genuine meaning by grouping stay-date vs creation-time vs last-modified filters and stating the at-least-one-filter constraint, which the schema does not encode. It stops short of explaining sort syntax or the start/end pairing of the two undescribed timestamp params.

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

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

States a specific verb and resource ("List reservations") plus paging, which immediately distinguishes it from the get_* siblings in the toolset. It does not explicitly contrast itself against alternatives such as get_hotel or list_rooms, but the reservation scope is unambiguous.

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?

"Give at least one filter" is an explicit usage precondition, and the scope requirements (read:reservation, read:customer) define when the call will succeed and when data degrades. No exclusion or alternative-tool routing is offered, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the required auth scope (read:room), which is genuinely useful operational context not present in structured fields. It does not mention pagination or ordering, but for a small read-only list tool that is a minor 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?

A single sentence plus a short scope note; the resource and returned fields are front-loaded and every clause carries information. 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 input parameters and no output schema, the description usefully compensates by enumerating the fields returned and the required scope. Only pagination/ordering behavior and the relation to sibling list tools are left unaddressed, which is a small gap for such a simple 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 to disambiguate and the baseline is 4. The description correctly implies a property-wide, unfiltered listing with no arguments.

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

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

States a specific verb ('List') and resource ('rooms of the property') and enumerates the returned fields (name, description, room type, active flag), so the agent knows exactly what it gets back. It does not explicitly contrast itself with the sibling thinkreservations_list_room_types, leaving the rooms-vs-room-types 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 prerequisite 'Needs scope read:room' is stated, which is real guidance for callers. However, there is no explicit when-to-use/when-not guidance and no mention of the obvious alternative (list_room_types) or of how to follow up once room identifiers are needed.

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 genuinely non-redundant context: the required scope 'read:room' and the fact that only name and id are returned, which sets expectations for a lean payload. Auth scoping is the kind of detail 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 short sentences, each doing distinct work: what it returns, how to use the result, and what scope is required. Return shape 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?

For a parameterless read tool with no output schema, the description supplies the essentials: return fields, required auth scope, and the follow-up chaining pattern. Only a note on result volume (all room types, no pagination) would make it fully self-contained.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies an unfiltered list of all room types.

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 room types') and even names the returned fields (name and id). That is enough to distinguish it from siblings like list_rooms, list_rate_types, and get_inventory 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?

'Use the ids to filter inventory and daily rates' tells the agent exactly what to do next, implicitly routing to get_inventory and get_daily_rates. It stops short of an explicit exclusion (e.g., when to prefer list_rooms), so it is strong guidance rather than a full use/don't-use rule.

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