feat: improve skill guidance for partial matches, anchor hotels, and prompt (#3)

victorpoluceno · claude · web-flow · commit 5c9757a7c380 · 2026-04-09T15:39:03.000-03:00
* feat: handle partial matches in result presentation

When filters are active, the MCP server may return hotels that only
match some criteria (isPartialMatch). Rank full matches first, be
transparent about missing filters, and use match status to inform
category grouping.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* feat: add guidance for prompt, anchor hotels, and appliedFilters

Instruct the agent to pass the prompt parameter on every search,
present anchor hotels separately from alternatives, and use
appliedFilters to explain semantic filter mapping in partial matches.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* docs: fix README formatting and update connector instructions

Update claude.ai setup to use Connectors instead of Integrations,
fix bold syntax in tool list, and add missing blank lines before
code blocks.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* chore: remove internal repo reference from AGENTS.md

Replace private Andromeda repo link with the public MCP server docs
URL before open-sourcing.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* docs: rename README title to Vio Skill

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -24,7 +24,7 @@ This is the Vio MCP Skill — a portable skill that teaches AI agents how to sea
 - Write in **imperative form**, not second person ("Search for hotels" not "You should search")
 - The `description` field in frontmatter must use **third person** with specific trigger phrases
 - Tool schemas live in `references/tool-reference.md` — update this when the MCP server tools change
-- Source of truth for tool schemas: `src/mcp/tools/schemas/` in the [Andromeda](https://github.com/viodotcom/Andromeda) repo
+- Source of truth for tool schemas: the Vio MCP server (`https://mcp.vio.com/docs/`)
 
 ## Testing
 
diff --git a/README.md b/README.md
@@ -1,13 +1,13 @@
-# Vio MCP Skill
+# Vio Skill
 
 A portable skill for AI agents that provides conversational hotel search via the [Vio MCP server](https://mcp.vio.com/docs/). Search hotels, compare prices, read reviews, and explore room options through natural conversation.
 
 ## What It Does
 
 The `/vio` skill teaches agents to use two MCP tools:
 
-- **`search_hotels`** — Discover hotels by location, coordinates, or name. Supports filters (star rating, amenities, property type, price range), sorting, and pagination.
-- **`get_hotels`** — Fetch detailed data for specific hotels: reviews, rooms, FAQ, policies, price analytics, and more.
+- `**search_hotels**` — Discover hotels by location, coordinates, or name. Supports filters (star rating, amenities, property type, price range), sorting, and pagination.
+- `**get_hotels**` — Fetch detailed data for specific hotels: reviews, rooms, FAQ, policies, price analytics, and more.
 
 ## How It Works
 
@@ -38,9 +38,9 @@ Or build locally: `mise run zip`
 1. Download `vio.zip` from [Releases](https://github.com/viodotcom/mcp-skill/releases)
 2. Go to **Customize → Skills** and upload `vio.zip`
 3. Enable the skill
-4. Add the Vio MCP server under **Customize → Integrations → MCP**:
-   - **Type:** HTTP
-   - **URL:** `https://mcp.vio.com/mcp?api_key=YOUR_API_KEY`
+4. Add the Vio MCP server under **Customize → Connectors**:
+  - **Type:** HTTP
+  - **URL:** `https://mcp.vio.com/mcp?api_key=YOUR_API_KEY`
 5. Start a conversation and try: "Find hotels in Amsterdam for next weekend"
 
 ### OpenClaw
@@ -123,11 +123,13 @@ https://mcp.vio.com/mcp?api_key=YOUR_API_KEY
 ## Usage
 
 Invoke the skill directly:
+
 ```
 /vio Paris, 3 nights in July, budget under 150 EUR
 ```
 
 Or let the agent trigger it automatically when you mention hotel search:
+
 ```
 Find me a 4-star hotel in Amsterdam with a pool
 ```
@@ -154,4 +156,4 @@ README.md                       # This file
 
 ## License
 
-[BSD 3-Clause](LICENSE)
+[BSD 3-Clause](LICENSE)
diff --git a/SKILL.md b/SKILL.md
@@ -85,12 +85,12 @@ Map user preferences to tool parameters:
 
 ### 2. Initial Search
 
-Call `search_hotels` with the user's location via `queries`. ALWAYS include `analytics` and `insights` alongside the defaults: `include: ['location', 'rating', 'classification', 'media', 'offer', 'analytics', 'insights']`.
+Call `search_hotels` with the user's location via `queries`. Always pass `prompt` with a clean English version of the user's query (strip any PII). ALWAYS include `analytics` and `insights` alongside the defaults: `include: ['location', 'rating', 'classification', 'media', 'offer', 'analytics', 'insights']`.
 
 - **Analytics** — price comparison vs similar hotels (cheaper/same/expensive), trends, and historical data. E.g., "Priced 15% below similar hotels in the area."
 - **Insights** — AI-generated review summaries per category (Facilities, Cleanliness, Rooms, Service, Location, Food). E.g., "Guests consistently praise the rooftop terrace and breakfast."
 
-When searching for a specific hotel by name, pass the full hotel name in `queries` (e.g., `queries: ["Hilton Amsterdam"]`). This returns the hotel plus similar alternatives.
+When searching for a specific hotel by name, pass the full hotel name in `queries` (e.g., `queries: ["Hilton Amsterdam"]`). This returns the hotel plus similar alternatives. The searched hotel is marked with `isAnchorHotel: true` and its ID appears in `anchorHotelIds`. Always present the anchor hotel first and separately from alternatives — it's what the user asked for, not a recommendation.
 
 For multiple locations or hotels, pass up to 3 queries: `queries: ["Paris", "London"]`.
 
@@ -100,7 +100,9 @@ Use `searchMode: 'fast'` (default) for initial searches — it returns results q
 
 Before presenting, rank hotels by how well they match the user's expressed intent. Consider what they asked for — destination, vibe, priorities, constraints, occasion, budget — and reorder results so the best matches come first. Use all available data to inform the ranking: location, rating, classification, facilities, analytics, insights, and any other signals in the response. Analytics (price vs similar hotels) and insights (review summaries) tend to carry strong signal.
 
-Group the ranked hotels into 2-3 categories based on the data (e.g., "Best Value", "Top Rated", "Central Location", "Luxury Picks"). Place the strongest-match category first.
+**Partial matches:** When filters are active, some hotels may have `isPartialMatch: true` — they matched some but not all requested filters. Always rank full matches above partial matches. When presenting partial matches, be transparent: mention which requested filters they don't meet (e.g., "doesn't have a pool but scores high on everything else you asked for"). Use `appliedFilters` from the response to see what filters were actually applied after semantic matching — this helps explain the gap between what the user typed and what was matched (e.g., user said "pool" but the applied filter is "Swimming Pool"). If the results are mostly partial matches, explain why — the filter combination may be uncommon in that market (e.g., "2-star hotels with a pool are rare in Amsterdam — these are the closest matches"). Never present a partial match as if it fully satisfies the user's criteria.
+
+Group the ranked hotels into 2-3 categories based on the data (e.g., "Best Value", "Top Rated", "Central Location", "Luxury Picks"). Place the strongest-match category first. When there's a mix of full and partial matches, use this to inform grouping — e.g., a "Full Match" or "Closest to What You Asked" category first, followed by a "Worth Considering" category for strong partial matches.
 
 For each category, write a `##` heading (2-4 words max), then a short paragraph (2-3 sentences) describing why these hotels are grouped together. Bold key attributes — star ratings, amenities, neighborhoods, guest rating ranges — so users can scan quickly.
 
@@ -113,7 +115,7 @@ After the category description, list each hotel in this format:
 - [match points tied to user intent]
 ```
 
-The last line should explain why this hotel fits (or doesn't) what the user asked for, in plain language. Tie it back to their expressed intent — e.g., "walking distance to the historic centre", "rooftop pool fits the honeymoon vibe", "priced 15% below similar hotels". Include negative match points when relevant — e.g., "farther from the beach than you described".
+The last line should explain why this hotel fits (or doesn't) what the user asked for, in plain language. Tie it back to their expressed intent — e.g., "walking distance to the historic centre", "rooftop pool fits the honeymoon vibe", "priced 15% below similar hotels". Include negative match points when relevant — e.g., "farther from the beach than you described". For partial matches, explicitly note the missing filter — e.g., "no pool, but strong on location and price".
 
 Rules:
 - Every hotel must appear in exactly one category — never repeat a hotel across categories
