Skip to main content
Glama
negm17111995

MAQAMI Travel

by negm17111995
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Get hotel highlights

post_data_hotel_highlights
Read-only

Overview

Instructions

Overview

Generate short, AI-written "Smart Highlight" cards for a hotel. Each highlight is a title plus a one or two sentence description, generated directly in the requested language.

Pricing: $0.02 per request

Rate Limiting: This endpoint is rate-limited to 10 requests per minute. Exceeding this limit will result in a 429 Too Many Requests response.

When to Use

  • Hotel detail pages - Show a few compelling reasons to consider a property

  • Partner-specific tone - Adjust voice and emphasis per surface via tone, style and per-highlight context

What You Get

  • Exactly count highlights, always, in the requested order

  • type echoed back from the request so you can map each card to your own UI

  • generated indicating whether the copy is AI-generated or template fallback

Behaviour

Hotel facts are resolved server-side from hotelId; the caller never supplies them. The model sees the name, city, country, street address, parking, and description, plus a sample of facilities, rooms, policies, and nearby places (with a server-computed distance phrase: on the property, short walk, short drive, or longer drive; farther places are omitted), guest sentiment strengths when stored (not drawbacks), and classification (star rating, hotel type, chain). Generated copy is grounded in those facts. Straight apostrophes in titles and descriptions are normalized to typographic apostrophes. Enterprise API keys also omit wifi and the phrase modern amenities from the facts and from the copy, and they omit review-style wording such as guests say. Other API keys still return wifi and connectivity copy when the request asks for it. When tone or style specify length or format, those rules override the default title and description lengths.

If AI generation fails, the endpoint still returns 200 with the requested number of neutral template highlights and generated: false. It never returns an empty array for a valid hotel.

Results are cached, so repeated calls with an identical request body return identical copy.

tone and style are truncated to 200 characters (5,000 for enterprise accounts). Each highlight context is truncated to 300 characters (10,000 for enterprise accounts).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
toneNoGlobal writing guidance, e.g. `professional and inviting` or `calm and practical`. Truncated to 200 characters (5,000 for enterprise accounts).
countNoNumber of highlights to generate. If `highlights` is supplied, `count` must equal its length.
styleNoFormatting preferences such as title or description length. When supplied, these rules override the default title (2-4 words) and description (~180 characters) lengths. Truncated to 200 characters (5,000 for enterprise accounts).
hotelIdYesUnique ID of the hotel (MAQAMI format)
languageYesLanguage code. Highlights are generated directly in this language.
highlightsNoPer-highlight guidance. Omit for generic generation. When supplied, its length must equal `count` and the response preserves this order.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.0.10
    • changedInput schema / properties / highlights / items / properties / context / description
      Previous value: -"Free-text guidance describing what this highlight should emphasise. Treated as topic guidance only; claims not supported by the hotel's data will not be invented."New value: +"Free-text guidance describing what this highlight should emphasise. Treated as topic guidance only; claims not supported by the hotel's data will not be invented. Truncated to 300 characters (10,000 for enterprise accounts)."
    • changedInput schema / properties / style / description
      Previous value: -"Formatting preferences such as title or description length."New value: +"Formatting preferences such as title or description length. When supplied, these rules override the default title (2-4 words) and description (~180 characters) lengths. Truncated to 200 characters (5,000 for enterprise accounts)."
    • changedInput schema / properties / tone / description
      Previous value: -"Global writing guidance, e.g. `professional and inviting` or `calm and practical`."New value: +"Global writing guidance, e.g. `professional and inviting` or `calm and practical`. Truncated to 200 characters (5,000 for enterprise accounts)."
  2. Changed1 schema field changedv1.0.6
    • changedInput schema / properties / hotelId / description
      Previous value: -"Unique ID of the hotel (liteAPI format)"New value: +"Unique ID of the hotel (MAQAMI format)"
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Far exceeds the annotation baseline: pricing ($0.02/request), rate limiting (10 rpm with 429), server-side fact resolution and what facts the model sees, enterprise-key exclusions, apostrophe normalization, truncation limits, and a detailed failure mode (returns 200 with template highlights and generated: false, never an empty array). Caching behavior and the count==highlights length invariant are also disclosed. One subtle tension: the caching note implies identical requests return identical copy, which sits oddly against idempotentHint=false, though it is not a safety-relevant 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?

Well front-loaded and organized under Overview / When to Use / What You Get / Behaviour, so an agent can scan it quickly. It is somewhat long, and the truncation limits (200/5,000 and 300/10,000 chars) are duplicated verbatim from the schema, which is minor waste rather than bloat.

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

Completeness5/5

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

Despite having no output schema, the description fully documents the return shape (exactly `count` highlights in order, `type` echoed back, `generated` flag) plus failure and caching behavior, which is everything an agent needs to invoke and interpret the result correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning on top: it states hotelId facts are resolved server-side and never supplied by the caller, that context is treated as topic guidance and unsupported claims are not invented, and that style length/format rules override the default title (2-4 words) and description (~180 char) lengths. Some truncation limits are merely restated from 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.

Purpose5/5

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

The description opens with a specific verb and resource: 'Generate short, AI-written "Smart Highlight" cards for a hotel,' and immediately clarifies the output shape (a title plus a one/two-sentence description in the requested language). This clearly distinguishes it from siblings like get_data_hotel (returns raw hotel data) and get_data_reviews (returns reviews). An agent can tell what this does without opening the schema.

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

Usage Guidelines4/5

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

A dedicated 'When to Use' section gives concrete scenarios (hotel detail pages, partner-specific tone) and explains how tone/style/context tune the output. It does not name sibling tools or state when NOT to use it, but for a generation endpoint with no true functional alternative, the context is clear and sufficient.

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

Deploy Server

Other Tools