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 서버보다 더 넓은 범위를 다룹니다.
더 깔끔한 인증 UX. 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 starttsx를 통한 핫 리로드:
npm run dev[x] v0.1 — 숙소, 예약, 달력, 대화, 재무 및 상태 확인을 아우르는 10가지 읽기 전용 도구
[ ] v0.2 — 작업(list_tasks, get_task); 취소 정책; 사용자 지정 필드 읽기
[ ] v0.3 — 게스트 결제 읽기; 웹훅 읽기
[ ] v0.4+ — 명시적인 confirm: true 확인을 거치는 쓰기 작업(게스트 메시지 전송, 달력 블록 업데이트, 작업 생성)
요청 사항이 있으신가요? 이슈를 열거나 토론을 시작하세요.
자격 증명은 환경 변수에만 존재하며 이 서버에 의해 디스크에 기록되지 않습니다.
베어러 토큰은 프로세스 메모리에만 존재하며 영구 저장되지 않습니다.
v0.1은 전체적으로 읽기 전용이며, 이 코드베이스의 어떤 것도 Hostaway 데이터를 변경할 수 없습니다.
다중 숙소 운영자의 경우: Hostaway API는 제공한 자격 증명의 계정으로 범위가 지정된 데이터를 반환하므로 계정 간 액세스는 불가능합니다.
이슈 및 PR을 환영합니다. 코드베이스는 작고 읽기 쉽습니다. src/index.ts부터 시작하세요.
MIT — LICENSE를 참조하세요.
Kartik Vats (@prosperkartik) 제작 — Kodeit의 AI 엔지니어. PMS / OTA 통합 및 LLM 도구 분야에서 3년간의 프로덕션 작업 경험.
휴가용 임대 운영자나 호스피탈리티 기술 팀으로서 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.
