用于 Hostaway PMS 的模型上下文协议 (MCP) 服务器 — 将 Claude 连接到您的度假租赁运营中。
@prosperkartik/hostaway-mcp 将 Claude（在 Claude Code、Claude Desktop 或任何兼容 MCP 的客户端中）连接到您的 Hostaway 账户 — 包括房源、预订、日历可用性、房客消息和财务数据。由一位自 2022 年起为短期租赁运营商在生产环境中集成 Hostaway、Ciirus 和主要 OTA API（Airbnb、VRBO、Booking.com、Expedia、Marriott）的工程师编写。
Hostaway 是 Hostaway Inc. 的商标。本项目由社区构建，不隶属于 Hostaway，也未得到其认可。
三个原因：
工具覆盖范围广。 10 个只读工具涵盖房源、预订、日历、对话、财务和健康检查 — 比该领域的其他社区 MCP 服务器覆盖面更广。
更简洁的授权体验。 使用 Hostaway 在 API 设置页面提供的两个凭据（账户 ID + API 密钥），并在内部处理 OAuth 令牌交换。无需执行“先去别处生成承载令牌”的步骤。
由深谙 API 的开发者构建。 作者拥有 3 年以上 Hostaway / Ciirus 集成生产经验，设计决策基于真实的运营商工作流程，而不仅仅是 REST 端点。
Related MCP server: Lodgify MCP Server
所有 v0.1 工具均为只读。写入操作将在后续版本中推出，并受显式确认保护。
工具 | 描述 |
| 健康检查 — 返回已连接账户的统计数据（房源、预订、对话、业主报表、用户）。请先运行此项以确认设置是否有效。 |
| 列出账户下的房源 |
| 单个房源的详细信息 — 位置、容量、定价、声誉、渠道 URL |
| 列出预订，支持按到达日期范围和状态进行筛选 |
| 单个预订的详细信息 — 房客、日期、定价、渠道 |
| 房源在日期范围内的每日可用性 — 回答“房源 X 在 A 和 B 之间是否有空？” |
| 列出房客消息会话，包含未读状态和最后活动时间 |
| 仅列出包含未读房客消息的会话 — 回答“谁在等待回复？” |
| 单个会话的完整消息历史记录 |
| 列出业主财务报表 |
在您的 Hostaway 运营商账户中 → Settings → Hostaway API。生成 API 凭据。您将获得一个 Account ID 和一个 API Key。
claude mcp add hostaway \
--scope user \
-e HOSTAWAY_ACCOUNT_ID=your-account-id \
-e HOSTAWAY_API_KEY=your-api-key \
-- npx -y @prosperkartik/hostaway-mcp（或使用 --scope local 仅为当前项目安装。）
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 并添加：
{
"mcpServers": {
"hostaway": {
"command": "npx",
"args": ["-y", "@prosperkartik/hostaway-mcp"],
"env": {
"HOSTAWAY_ACCOUNT_ID": "your-account-id",
"HOSTAWAY_API_KEY": "your-api-key"
}
}
}
}重启 Claude Desktop。Hostaway 工具将出现在工具选择器中。
向 Claude 询问如下问题：
“运行 whoami 以确认 Hostaway 已连接。”
“列出我的 Hostaway 房源。”
“下周有哪些预订要办理入住？”
“房源 12345 在 5 月 10 日至 17 日期间有空吗？”
“我有未读的房客消息吗？”
“显示我与 [房客] 的对话。”
> List my Hostaway listings.
Found 3 listings:
| ID | Name | Location | Beds | Baths | Capacity | Status |
|-------|-------------------|-------------------|------|-------|----------|--------|
| 10001 | Sample Apt 2BR | Sample City, US | 2 | 2 | 4 | active |
| 10002 | Sample Loft | Sample City, US | 1 | 1 | 2 | active |
| 10003 | Sample Beachfront | Sample Beach, US | 3 | 2 | 6 | active |> Is listing 10001 available May 10–17?
# Calendar for listing 10001
8 days returned (2026-05-10 → 2026-05-17) · 6 available, 2 reserved, 0 blocked
| Date | Available | Status | Price | Min stay | Reserved | Blocked | Note |
|------------|-----------|----------|-------|----------|----------|---------|------|
| 2026-05-10 | ✓ | available| 220 | 2 | 0 | 0 | |
| 2026-05-11 | ✓ | available| 220 | 2 | 0 | 0 | |
| 2026-05-12 | ✗ | reserved | 220 | 2 | 1 | 0 | |
| ... |环境变量 | 必需 | 描述 |
| 是 | 您的 Hostaway 账户 ID（充当 OAuth |
| 是 | 您的 Hostaway API 密钥（充当 OAuth |
服务器在启动时将这些凭据交换为承载令牌，并在进程生命周期内将其缓存在内存中。
git clone https://github.com/prosperkartik/hostaway-mcp.git
cd hostaway-mcp
npm install
cp .env.example .env # fill in credentials
npm run build
npm start通过 tsx 进行热重载：
npm run dev[x] v0.1 — 10 个只读工具，涵盖房源、预订、日历、对话、财务和健康检查
[ ] v0.2 — 任务 (list_tasks, get_task)；取消政策；自定义字段读取
[ ] v0.3 — 房客付款读取；Webhook 读取
[ ] v0.4+ — 写入操作（发送房客消息、更新日历块、创建任务），受显式 confirm: true 保护
凭据仅存在于环境变量中 — 本服务器从不将其写入磁盘
承载令牌存在于进程内存中；无持久化存储
v0.1 是端到端的只读版本；此代码库中的任何内容都无法修改 Hostaway 数据
对于多房源运营商：Hostaway API 返回的数据范围仅限于您提供凭据的账户，因此无法进行跨账户访问
欢迎提交 Issue 和 PR。代码库很小且易于阅读；请从 src/index.ts 开始。
MIT — 参见 LICENSE。
由 Kartik Vats (@prosperkartik) 构建 — Kodeit 的 AI 工程师。拥有三年 PMS / OTA 集成和 LLM 工具开发的生产经验。
如果您是度假租赁运营商或酒店技术团队，并希望获得将 AI 接入运营的帮助，请通过 kodeit.io 或发送电子邮件至 prosperkartik@gmail.com 与我联系。
Fetch the full message history of a single conversation by id. Returns each message with direction (incoming/outgoing), timestamp, and body.
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | Yes | The numeric Hostaway conversation id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool returns messages with direction, timestamp, and body, but lacks details on potential pagination, ordering, or limits. Since no annotations are provided, the description partially fulfills the behavioral disclosure burden but is incomplete.
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 two sentences with no extraneous information. It front-loads the action and resource, making it efficient for quick understanding.
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?
Given the single required parameter and lack of output schema, the description adequately explains the return fields. However, it misses behavioral details such as pagination, maximum message count, or error scenarios, which reduces completeness slightly.
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 input schema covers 100% of parameters, and the description does not add meaning beyond the schema's description of conversation_id. The schema already adequately describes the parameter.
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 clearly states the tool fetches the full message history of a single conversation by ID, specifying the return fields (direction, timestamp, body). This distinguishes it from sibling tools like list_conversations and list_unread_conversations.
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 usage for retrieving detailed conversation messages, but does not explicitly state when to use this tool versus alternatives like list_conversations or list_unread_conversations. There are no exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full details for a single Hostaway listing by id. Returns location, capacity, pricing, reputation, and channel URLs as Markdown sections.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | The numeric Hostaway listing id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses a key behavioral trait: returns data as Markdown sections. It does not state read-only nature or auth needs, but for a GET operation this is acceptable.
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 cover purpose, resource, and return format with no redundancy. Efficiently front-loaded with key information.
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?
Given the tool's low complexity (1 param, no output schema), the description adequately conveys what the tool does and returns. Lacks only minimal extras like output format details.
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% for the single parameter, which already explains it. The description does not add new semantic value beyond the schema, earning baseline score of 3.
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 explicitly states 'Fetch full details for a single Hostaway listing by id', providing a clear verb and resource. It distinguishes from siblings like list_listings by specifying 'full details' and listing specific fields.
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 usage context by detailing the returned data (location, capacity, etc.), but lacks explicit when-to-use vs alternatives or exclusions. The sibling list_listings suggests this is for a single detailed view.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full details for a single Hostaway reservation by id. Returns guest info, dates, pricing breakdown, and channel details.
| Name | Required | Description | Default |
|---|---|---|---|
| reservation_id | Yes | The numeric Hostaway reservation id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should disclose read-only nature, error handling, or required permissions. It only mentions returns, not side effects or failure modes. Minimal behavioral insight.
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?
Single sentence, directly states purpose and key return attributes. No filler 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?
For a simple fetch tool with no output schema, it lists return fields. Missing error handling or edge case notes, but sufficiently complete for typical use.
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% for the single parameter, including a clear description. The description adds no extra meaning beyond 'by id'.
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?
Clearly states it fetches full details for a single reservation by id, and specifies exact components returned (guest info, dates, pricing, channel details). Distinct from sibling listing tools like list_reservations.
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?
Implied usage: use when you need full detail for a specific reservation. No explicit when-not or alternative tools mentioned, despite siblings like list_reservations providing contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the availability calendar for a single listing across a date range. Returns per-day availability, status, price, minimum stay, and reserved/blocked counts. Use this to answer 'is property X available between dates A and B?'
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | Calendar end date in YYYY-MM-DD format. | |
| listing_id | Yes | The numeric Hostaway listing id. | |
| start_date | Yes | Calendar start date in YYYY-MM-DD format. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies read-only through 'Get' and 'Returns' and describes output, but does not explicitly state safety or behavioral traits like rate limits or authentication.
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: first states action and output, second gives usage context. No extraneous words, front-loaded with purpose.
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?
Given no output schema, the description adequately explains return values (per-day availability, status, price, etc.) and the use case, making it complete for the tool's purpose.
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%, baseline is 3. The description reinforces the use of listing_id and date range but adds no new parameter meaning beyond 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 clearly states the tool retrieves availability calendar for a single listing across a date range, listing return fields and providing a concrete use case, distinguishing it 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?
The description explicitly says 'Use this to answer is property X available between dates A and B?', giving clear context for when to use. It does not specify alternatives or exclusions, but the sibling tools are sufficiently distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List guest message threads (conversations) on the connected Hostaway account. Returns a compact Markdown table with conversation id, guest, linked listing/reservation, unread state, and last activity time.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of conversations to return (1–50, default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description discloses the output format (Markdown table) but does not mention any side effects, rate limits, or concurrency behavior. It is a read operation, but this is not explicitly stated.
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 two sentences, front-loaded with the main purpose, and contains no redundant information. Every sentence adds value.
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?
Given the simple single-parameter schema and no output schema, the description is mostly complete. It explains what is returned and the output format. However, it lacks details on pagination or default ordering, which are minor gaps.
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% with the limit parameter fully described in the schema. The description does not add additional meaning beyond the schema, meeting the baseline for high coverage.
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 clearly states the tool lists guest message threads (conversations) from Hostaway and specifies the output format (Markdown table with conversation id, guest, linked listing/reservation, unread state, last activity time). It distinguishes from siblings like list_unread_conversations by implying it returns all conversations.
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 gives no explicit guidance on when to use this tool versus alternatives such as list_unread_conversations or get_conversation_messages. The purpose is clear but context for selection is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List properties (listings) on the connected Hostaway account. Returns a compact Markdown table with id, name, location, bedrooms/bathrooms, person capacity, and status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of listings to return (1–50, default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses output format (Markdown table with specific fields) but lacks details on auth requirements, rate limits, or read-only nature.
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?
Single sentence, front-loaded with purpose and output detail, no wasted 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?
For a simple list tool with one parameter and no output schema, description covers purpose and output format adequately. Could mention default sorting or filtering scope (e.g., active only).
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 already describes the single parameter 'limit' fully; description adds no extra meaning beyond schema, so baseline score of 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?
Description uses specific verb 'List' and resource 'properties (listings)', clearly distinguishing from sibling 'get_listing' which returns a single 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?
Implied usage for listing multiple properties, but no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives like 'get_listing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List owner financial statements on the connected Hostaway account. Returns a compact table of statement id, name, and status. Useful for revenue and payout reporting.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of statements to return (1–50, default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description adds value by stating output fields (id, name, status) but does not mention side effects, pagination, or authentication requirements.
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, front-loaded with purpose, no superfluous 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?
For a simple list tool with one parameter and no output schema, description adequately covers purpose and output, though missing potential filters.
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?
Only parameter 'limit' is fully documented in schema (100% coverage), so baseline applies; description adds no additional semantic meaning.
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?
Description clearly states verb (list) and resource (owner financial statements) and distinguishes from sibling tools that list other resources.
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?
Implied usage via 'useful for revenue and payout reporting' but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List reservations on the connected Hostaway account. Optional filters by arrival date range and reservation status. Returns a Markdown table with the most useful operational fields.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of reservations to return (1–50, default 20). | |
| status | No | Filter by reservation status (e.g. 'new', 'modified', 'cancelled', 'ownerStay', 'pending', 'awaitingPayment', 'declined', 'expired', 'inquiry', 'inquiryPreapproved', 'inquiryDenied', 'inquiryTimedout', 'inquiryNotPossible'). | |
| arrival_end_date | No | Filter reservations with arrival date on or before this YYYY-MM-DD. | |
| arrival_start_date | No | Filter reservations with arrival date on or after this YYYY-MM-DD. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full burden. It discloses the return format (Markdown table) and scope (most useful operational fields), but omits details like pagination behavior, default ordering, or authentication requirements.
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 concise with three sentences: purpose, filters, return format. It is front-loaded and wastes no words, though a bulleted structure could improve 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?
Given the tool's complexity (4 optional params, no output schema), the description covers core functionality and output format. However, it lacks details on pagination, default behavior when no filters are applied, and sort order.
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 parameters are well documented. The description adds context by labeling them as optional filters, but does not add meaning beyond what the schema already provides.
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 clearly states the tool lists reservations on the connected Hostaway account, with optional filters. It distinguishes from siblings like get_reservation by being a list operation.
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?
While the description mentions optional filters, it does not explicitly state when to use this tool versus alternatives like get_reservation for individual details. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List only guest message threads that have unread messages. The most useful tool for answering 'do I have any guests waiting on a reply?'
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of conversations to scan (1–50, default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool filters by unread status and guest threads, but it does not confirm whether the operation is read-only or if it has any side effects (like marking messages as read). With no annotations, more explicit behavioral disclosure would be beneficial.
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 with no wasted words. The description efficiently conveys the tool's core function and the primary use case.
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?
The tool is simple with one parameter and no output schema. The description explains what is returned (unread guest threads) but does not detail the format or fields. Given the simplicity and sibling context, it is largely 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?
The schema provides full coverage (100%) for the single 'limit' parameter with a clear description, so the description's lack of additional parameter detail is acceptable. The description does not add extra meaning beyond 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 explicitly states it lists only guest message threads with unread messages, and provides a concrete use case (answering 'do I have any guests waiting on a reply?'). This clearly differentiates it from siblings like list_conversations.
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 gives clear usage guidance by stating it's the most useful tool for checking for guests waiting on a reply. It does not explicitly mention when not to use it, but the naming and sibling context (list_conversations) make the distinction evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health-check tool — confirms credentials work and returns a quick summary of the connected Hostaway account: counts of listings, reservations, conversations, owner statements, and users. Use this first when setting up to verify the connection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return values and purpose, but without annotations, could be more explicit about safety (non-destructive nature) and error 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?
Two sentences include purpose, return summary, and usage guidance with no wasted 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?
Explains return values sufficiently for a simple health check, though lacks output schema and error details.
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?
No parameters exist, so schema coverage is 100%. Description adds no parameter info, but baseline is 4.
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 clearly states the tool is a health-check for credentials and returns a summary of account counts, distinguishing it from data-retrieval siblings.
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 recommends using this tool first when setting up to verify the connection, providing clear context on when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_conversation_messagesget_listingget_reservationlist_calendarlist_conversationslist_listingslist_owner_statementslist_reservationslist_unread_conversationswhoamiScored across 10 tools
Each tool targets a distinct resource and action: listings, reservations, calendar, conversations, statements, and account health. Even similar tools like list_conversations and list_unread_conversations are clearly differentiated by the unread filter.
Tools follow a verb_noun pattern consistently (list_listings, get_listing, list_reservations, get_reservation, list_calendar, get_conversation_messages, list_owner_statements, list_conversations). The only minor deviation is 'whoami', which breaks the pattern but is a common convention.
10 tools is well within the ideal range for a property management server. Each tool earns its place by covering a core aspect of the domain without redundancy or bloat.
The tool surface covers read-only operations for listings, reservations, calendar, conversations, and statements, plus a health check. While there are no write/update tools, the server appears intentionally informational; minor gaps like batch availability or reservation creation are not critical for typical queries.
Manage Hostaway listings, reservations, calendar, guest messages, reviews and tasks.
Read-only AI access to HAVN properties, leads, tasks, files, media, and analytics.
Vacation rental discovery, direct booking, and property protection for AI agents.
Manage OwnerRez properties, bookings, guests, quotes and inquiries.
