Skip to main content
Glama

Available Coupons

query_available_coupons
Idempotent

Ensure automatic coupon entitlement and query the amount payable; does not reserve quota. 普通 ToC 酒店查询可匿名,user_key 可选;下单、订单查询、取消和支付需要客户端安全配置的 user_key。 在验价后使用相同酒店、日期、币种和整笔总价查询可用券;预览不占名额,须让用户确认券后实付再创建。 查询失败时先区分参数/鉴权错误和上游暂时失败:修正参数或重新授权后再调用,仅暂时失败可有限重试;不得把错误或空结果改述成成功。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "hotel_id": "<hotel_id>",
      "rate_code": "<rate_code>",
      "check_in_date": "<check_in_date>",
      "check_out_date": "<check_out_date>",
      "currency": "<currency>",
      "total_price": "<total_price>",
      "user_key": "<user_key>"
    },
    "name": "query_available_coupons"
  }
}

Input Schema

NameRequiredDescriptionDefault
currencyYes核实报价的 ISO 4217 币种;订单实际以鉴权账号结算币种为准,本参数不改变账号币种。
hotel_idYesTourMind 酒店 ID,数字字符串;从地点/酒店搜索返回取得,不使用 Google place_id。
user_keyYes由可信本地客户端配置的 TourMind 用户凭证;勿让用户在聊天中粘贴。普通 ToC 查询可省略,订单/支付操作必填;OAuth 与 ToB 不接受此字段。
rate_codeYes不透明报价代码,原样传递;验价使用 query_room_rates 返回值,下单使用 check_room_availability 最新返回值,酒店/日期/入住人数必须一致。
total_priceYes最新验价的全部房间、整段入住总价,currency 主单位,必须大于 0;未含另列 Stripe 手续费。价格变化须先征得用户确认。
check_in_dateYes入住日期,YYYY-MM-DD。
check_out_dateYes离店日期,YYYY-MM-DD,必须晚于 check_in_date。

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / description
      Previous value: -"返回字段说明(不增加校验约束;缺失、零值和 null 按各字段说明解释):\n返回值 [object] 必有字段=ok: 业务响应信封;字段缺失表示没有提供,不能自动补零。数组的 null 与 [] 都不含条目,但 null 不承诺完成了该部分查询。\n返回值.data [object] 必有字段=coupons,message: 可用券预览,不占用名额。金额为 currency 主单位。\n返回值.data.coupons [array]: 当前可选优惠券\n返回值.data.coupons[] [object] 必有字段=coupon_code,discount_amount,payable_amount,currency,remaining_quantity\n返回值.data.coupons[].coupon_code [string]\n返回值.data.coupons[].currency [string]: 金额币种 ISO 4217。\n返回值.data.coupons[].discount_amount [number]\n返回值.data.coupons[].payable_amount [number]: 订单金额加 Stripe 手续费后的实际应付总额,currency 主单位;尚未支付。\n返回值.data.coupons[].remaining_quantity [integer]\n返回值.data.message [string]: 使用说明\n返回值.error [string]: 业务失败说明,不作为可重试或成功的唯一依据。\n返回值.error_code [string]: 鉴权等机器可读错误码,仅在错误路径提供。\n返回值.ok [boolean]: 业务是否成功。false 时读取 error/reason;工具执行错误也可能通过 MCP isError 返回而没有 structuredContent。\n返回值.reason [string] 取值=[\"invalid_request\",\"hotel_not_found\",\"upstream_timeout\",\"upstream_error\",\"hotel_detail_unavailable\"]: 失败原因:invalid_request=参数无效,hotel_not_found=酒店不存在,upstream_timeout=上游超时,upstream_error=上游失败,hotel_detail_unavailable=酒店详情不可用。成功空结果的 no_matching_live_room 位于 data.reason;批量逐项判断,不把一项失败当成整批失败。\n返回值 的分支 1:\n返回值 必有字段=data\n返回值.ok 取值=[true]\n返回值 的分支 2:\n返回值 必有字段=error,reason\n返回值.ok 取值=[false]\n"New value: +"返回字段说明(不增加校验约束;缺失、零值和 null 按各字段说明解释):\n返回值 [object] 必有字段=ok: 业务响应信封;字段缺失表示没有提供,不能自动补零。数组的 null 与 [] 都不含条目,但 null 不承诺完成了该部分查询。\n返回值.data [object] 必有字段=coupons,message: 可用券预览,不占用名额。金额为 currency 主单位。\n返回值.data.coupons [array]: 当前可选优惠券\n返回值.data.coupons[] [object] 必有字段=coupon_code,discount_amount,payable_amount,currency,remaining_quantity\n返回值.data.coupons[].coupon_code [string]\n返回值.data.coupons[].currency [string]: 金额币种 ISO 4217。\n返回值.data.coupons[].discount_amount [number]\n返回值.data.coupons[].payable_amount [number]: 使用该优惠券后的整笔预订房费,等于 total_price 减 discount_amount,currency 主单位,不含支付手续费;仅为预览,未占用优惠券名额。\n返回值.data.coupons[].remaining_quantity [integer]\n返回值.data.message [string]: 使用说明\n返回值.error [string]: 业务失败说明,不作为可重试或成功的唯一依据。\n返回值.error_code [string]: 鉴权等机器可读错误码,仅在错误路径提供。\n返回值.ok [boolean]: 业务是否成功。false 时读取 error/reason;工具执行错误也可能通过 MCP isError 返回而没有 structuredContent。\n返回值.reason [string] 取值=[\"invalid_request\",\"hotel_not_found\",\"upstream_timeout\",\"upstream_error\",\"hotel_detail_unavailable\"]: 失败原因:invalid_request=参数无效,hotel_not_found=酒店不存在,upstream_timeout=上游超时,upstream_error=上游失败,hotel_detail_unavailable=酒店详情不可用。成功空结果的 no_matching_live_room 位于 data.reason;批量逐项判断,不把一项失败当成整批失败。\n返回值 的分支 1:\n返回值 必有字段=data\n返回值.ok 取值=[true]\n返回值 的分支 2:\n返回值 必有字段=error,reason\n返回值.ok 取值=[false]\n"
  2. Added

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already mark idempotent=true, destructive=false, openWorld=true, so the marginal bar is met by the description's added quota semantics ('preview does not consume quota / does not reserve quota') and its error-handling contract, including the prohibition on recasting errors or empty results as success. It also discloses the auth model: anonymous ToC hotel queries may omit user_key, while ordering, order lookup, cancellation, and payment require a client-configured user_key. readOnlyHint=false is consistent with the 'automatic coupon entitlement' side effect, so there is no contradiction.

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

Conciseness4/5

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

The purpose and the 'does not reserve quota' caveat are front-loaded, and the remaining sentences cover workflow placement and failure handling without filler. The mixed English/Chinese register and the somewhat cryptic 'Ensure automatic coupon entitlement' opener cost a point in clarity.

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

Completeness4/5

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

With an output schema present and all 7 required parameters fully documented in the schema, the description does not need to explain return values, and it correctly spends its space on workflow position, quota side effects, auth requirements, and error triage. Slightly more explicit routing to the verification tool would make it complete for this complexity.

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

Parameters3/5

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

Schema description coverage is 100%, including the meaning of currency, rate_code provenance, total_price semantics, and the user_key policy, so the schema already carries the parameter burden. The description only restates the consistency requirement (same hotel, dates, currency, total price) rather than adding format or edge-case meaning. Baseline 3 is appropriate.

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

Purpose4/5

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

The description states a specific verb and resource: query available coupons and the amount payable, with an explicit scope caveat that it does not reserve quota. The opening phrase 'Ensure automatic coupon entitlement' is ambiguous (entitlement vs. listing) and no sibling tool is named, so an agent must infer the boundary with query_room_rates from phrasing rather than an explicit name, keeping this at 4.

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

Usage Guidelines4/5

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

It gives a concrete precondition and ordering rule: call after price verification (验价) using the same hotel, dates, currency, and full total price, and have the user confirm the coupon-adjusted amount before creating the order. It also adds a retry policy distinguishing parameter/auth errors (fix or re-authorize) from temporary upstream failures (limited retries allowed). What it lacks is an explicit named alternative for obtaining prices without coupons, which keeps it from a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.