Read-only MCP server for short-term rental owners in Poland. Query reservations, availability, pricing, guest reviews, and monthly stats via 10 tools. OAuth 2.1 with PKCE or static Bearer token.
Scored across 10 tools
Each tool has a distinct purpose: reservations, availability, pricing, stats, blocks, reviews, messages, apartments, and account identity are clearly separated. Even similar concepts like get_availability and list_blocks are explicitly differentiated.
The get_* and list_* prefixes create a predictable pattern, and whoami is the only tool that breaks the verb_noun convention. It is still recognizable as a standard identity command, so the inconsistency is minor.
10 tools is well-scoped for a property-management read/query API. Each tool covers a distinct area without unnecessary duplication or overwhelming breadth.
Core read-only domain coverage is strong: apartments, reservations, availability, pricing, stats, messages, reviews, blocks, and auth. The main gap is the lack of any write/modification tools, which is acceptable if this is intentionally read-only but leaves no way to manage reservations or pricing through the server.
Occupied check-in/check-out date ranges, no guest data. Defaults to today through +365 days; the range cannot exceed 366 days.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| apartment_id | No | Restrict to one apartment. Must belong to this account. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this read-only and non-destructive. The description adds useful behavioral details beyond the annotations: it returns only occupied ranges, excludes guest data, and enforces a 365-day default and 366-day maximum range. It does not describe authorization or error behavior, but these are less critical given the read-only hint.
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 compact, front-loads the core resource, and includes only high-value constraints. No filler or redundant restatement of the tool name.
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 default range, maximum range, and 'no guest data' boundary cover the most important operational context. The apartment restriction is in the schema, and the output schema exists, so the description is sufficiently complete for a simple read-only availability endpoint.
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 low for from/to, and the description only partially compensates by explaining the default range and maximum span. It does not explicitly map 'from' and 'to' parameters to the date range or clarify accepted formats, so an agent still has to infer some parameter 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?
The description identifies the resource ('occupied check-in/check-out date ranges') and a key boundary ('no guest data'), which distinguishes it from guest-centric tools like list_reservations or get_reservation. However, it lacks an explicit verb like 'returns' or 'lists', so the agent must infer the operation from the tool name.
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 provides default date behavior and a length constraint, but gives no explicit guidance on when to choose this tool over alternatives such as get_reservation or list_reservations. The only indirect clue is 'no guest data,' which is not enough to direct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Seasonal price overrides, minimum-stay rules and extra fees — the pricing configuration, not a computed quote. The base nightly rate lives on the apartment record (see list_apartments), not here.
| Name | Required | Description | Default |
|---|---|---|---|
| apartment_id | No | Restrict to one apartment. Must belong to this account. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about what the tool does NOT return (not a computed quote, base rate lives elsewhere), which is valuable. It doesn't describe pagination or response shape, but the output schema exists and the read-only nature is already annotated.
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 waste. The core scope is front-loaded, and the clarifying exclusions are placed right after. Every sentence earns its place.
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 read-only, single-parameter tool with an output schema, the description is nearly complete. It clarifies scope, exclusions, and where to find related data. The only minor gap is not naming a sibling for computed quotes, but the description's explicit 'not a computed quote' is sufficient.
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%, so the schema already documents the single parameter. The description adds the context that apartment_id must belong to this account, which is a small but useful addition beyond the schema. Baseline 3 is appropriate.
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 states a specific verb and resource: retrieving pricing configuration (seasonal overrides, minimum-stay rules, extra fees). It explicitly distinguishes itself from a computed quote and from the base nightly rate, which is enough to differentiate it from siblings like get_availability and list_apartments.
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 clearly indicates when to use this tool: when you need the pricing configuration, not a computed quote. It also points to list_apartments for the base nightly rate. It doesn't explicitly name an alternative for computed quotes, but the exclusion is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single reservation by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Reservation id, from list_reservations. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Get' is consistent. It does not add any additional behavioral details (e.g., error handling, return size, null when not found), but given the annotations cover the safety profile and the output schema covers return shape, the description meets the lower bar set for annotated tools.
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 a single, tightly worded sentence with no fluff. It places the core action ('Get') and target resource upfront, and it is exactly the length required for this simple tool.
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 tool with only one required parameter, existing output schema, and annotations that clearly mark it read-only, the description is sufficient. It could briefly mention behavior when id does not exist or the source of the id, but those gaps are minor given the overall structured metadata.
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% – the id parameter is fully described with its type and source ('Reservation id, from list_reservations'). The description 'by id' adds no new meaning beyond the schema, so the baseline of 3 is appropriate.
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 verb 'Get', the resource ('a single reservation'), and the specific scope ('by id'), which distinguishes it from the sibling 'list_reservations' and other get_* tools. An agent can immediately understand what this tool 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. The parameter description mentions 'Reservation id, from list_reservations', but the tool description itself does not explain how to obtain the id or when one would need this over a list/filter approach.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Monthly occupancy and revenue for one apartment, confirmed reservations only — the same numbers as the panel's Statystyki page. apartment_id is required: occupancy/revenue from apartments with different nightly rates can't be meaningfully summed.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Trailing months to include, defaults to 12. | |
| apartment_id | Yes | Required. From list_apartments. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details beyond those annotations: only confirmed reservations are included, the numbers match a specific UI panel, and results are scoped to one apartment. This helps the agent understand what the tool actually returns and what assumptions it makes.
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 filler. The main output and scope are front-loaded, and the second sentence justifies the required parameter without redundancy. Every clause adds value, and the length is appropriate for the tool's complexity.
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?
With a high-coverage schema, read-only annotations, and an output schema available, the description covers everything an agent needs to invoke this tool correctly: what it returns, its scope, its data source (confirmed reservations), and the mandatory parameter. There are no missing prerequisites or ambiguous behaviors that would prevent a correct call.
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%, so the schema already documents both parameters, including that apartment_id is required and comes from list_apartments. The description adds a useful rationale for apartment_id — different nightly rates make cross-apartment summing meaningless — but it does not add new syntax or format details for months. The schema carries the main parameter documentation burden, so a baseline 3 is appropriate.
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 states exactly what the tool provides: monthly occupancy and revenue for one apartment, using only confirmed reservations. It also anchors to the panel's Statystyki page, making it easy to distinguish from sibling tools like get_pricing or get_reservation. It lacks an explicit verb like 'returns' or 'retrieves,' but the noun phrase is specific enough to identify the purpose.
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 context: it is for one apartment and uses the same numbers as the Statystyki panel, which tells an agent when this tool matches the user's request. It also explains why apartment_id is required and why multi-apartment aggregation is invalid, effectively warning against calling it for portfolio-level stats. It does not explicitly name alternative tools or say 'do not use for X,' but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's apartments and their ids. Call this before any tool that takes apartment_id — get_stats requires it, the rest treat it as an optional filter.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about scope ('the account's apartments') and the importance of IDs for downstream calls, but it does not describe return format or pagination. With the output schema available, this is adequate but not exceptional.
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 deliver the core action first, then the critical usage context. Every word earns its place; there is no fluff or redundant restating of the tool name.
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 parameterless list operation with read-only annotations and an output schema, the description is complete. It tells the agent what the tool returns, the scope, and when to call it relative to other tools. Nothing essential is missing.
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 tool has zero parameters and the schema covers 100% of them, so there is no parameter documentation burden on the description. The description's mention of 'ids' is relevant to what callers will use as input elsewhere, but no parameter explanation is needed here.
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 states a clear verb and resource: 'List the account's apartments and their ids.' This is easily distinguished from sibling tools like list_blocks or list_reservations, and the mention of ids directly signals the tool's role in supplying apartment_id values.
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 explicit when-to-use guidance: 'Call this before any tool that takes apartment_id.' It also clarifies the distinction among consumers by noting get_stats requires the ID while other tools treat it as optional, which is exactly the kind of routing information an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Owner-created blocked date ranges (maintenance, personal use). Not reservations — no guest, no price.
| Name | Required | Description | Default |
|---|---|---|---|
| apartment_id | No | Restrict to one apartment. Must belong to this account. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the nature of the data (owner-created, not reservations), but doesn't disclose details like whether past blocks are included or how the list is ordered. This is acceptable for a read-only list tool.
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 short sentences with no filler. The core definition is front-loaded, and the clarifying contrast with reservations is concise and valuable.
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 read-only list tool with one optional parameter and an output schema, the description is nearly complete. It could mention whether the list is filtered by date range or includes historical blocks, but the annotations and schema cover the essential safety and parameter 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%, so the single optional parameter apartment_id is already fully documented in the schema. The description doesn't add extra meaning about the parameter, but the baseline of 3 applies because the schema does the heavy lifting.
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 identifies the resource ('Owner-created blocked date ranges') and distinguishes it from reservations with an explicit contrast ('Not reservations — no guest, no price'). This makes it easy for an agent to understand what list_blocks returns and how it differs from 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?
The description implies the tool is for viewing owner-created blocks, and the contrast with reservations helps an agent choose it over list_reservations. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Message history for one reservation — everything sent to the guest, automatic mail included. The same thread the panel shows.
| Name | Required | Description | Default |
|---|---|---|---|
| reservation_id | Yes | Reservation id, from list_reservations. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral detail beyond that: it specifies the scope includes 'everything sent to the guest, automatic mail included', which is non-obvious and valuable. It also confirms consistency with the UI ('The same thread the panel shows'), giving the agent confidence in output relevance. No contradictions with annotations; this is an additive transaction.
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 a single, concise sentence that packs essential details: the scope (one reservation), the inclusion of automatic mail, and the UI consistency. It is front-loaded with the core purpose and has zero filler. Every phrase earns its place.
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 tool with one parameter, a high-coverage schema, existing output schema, and read-only annotations, the description is complete. It tells the agent what the output will contain (all messages sent), the scope, and the relationship to the panel. No missing information that would prevent correct invocation or interpretation.
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% (reservation_id is described with a clear source: 'from list_reservations'). The tool description does not add any extra parameter semantics beyond the schema. Per the rubric, when schema coverage is high, baseline is 3, and the description does not compensate with additional parameter guidance (e.g., format, constraints). This is adequate but not enhanced.
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 verb (list is implied by 'Message history') and the specific resource: messages for one reservation. It distinguishes itself from siblings by specifying it covers 'everything sent to the guest, automatic mail included', which is specific to this tool and not described in list_reservations or get_reservation. The phrase 'The same thread the panel shows' further anchors its distinct scope.
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 context: it is for a single reservation ('for one reservation') and is for message history. However, it does not explicitly mention when not to use it or name alternative tools (e.g., get_reservation for details, list_reservations for reservation summaries). It implies usage based on the need for message history, but lacks explicit exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List reservations across the account's apartments, newest first, cursor-paginated. from/to filter by stay date (check-out after from, check-in before to), not by when the reservation was created.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | YYYY-MM-DD. Only reservations whose stay starts before this date. | |
| from | No | YYYY-MM-DD. Only reservations whose stay ends after this date. | |
| after | No | Pagination cursor — pass pagination.next_after from the previous call. | |
| limit | No | Page size, defaults to 100. | |
| status | No | ||
| apartment_id | No | Restrict to one apartment. Must belong to this account. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing a safe read operation. The description adds behavioral context beyond annotations: cursor-based pagination, 'newest first' ordering, and the exact filtering logic (check-out after from, check-in before to). With annotations covering the safety profile and the description explaining pagination semantics, a 4 is appropriate.
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 the core scope front-loaded ('List reservations across the account's apartments, newest first, cursor-paginated') and the subtle filter semantics stated crisply. There is no wasted wording; each phrase earns its place.
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 list tool with zero required parameters, an output schema, and safe annotations, the description covers the essential nuances: pagination behavior, ordering, and stay-date filtering. The only minor gap is that it doesn't state the default behavior when no filters are provided, but that is largely inferable from the schema. Sibling differentiation is strong.
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 83%, so most parameters (after, limit, status, apartment_id) are already well-documented. The description adds value by clarifying from/to beyond the schema definitions, but for the other parameters it repeats or implies what the schema already provides. Baseline 3 is correct given the high schema 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 states a specific verb ('List'), a precise resource ('reservations across the account's apartments'), and clarifies ordering and pagination. It also distinguishes the from/to filters from creation-date filtering, which prevents misinterpretation and separates it from sibling get_reservation.
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 when to use it: to list reservations across the account. It explicitly explains the from/to date semantics, which is critical for correct invocation. It doesn't explicitly say when not to use it or name alternatives, but the purpose is clear enough that an agent can infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Guest reviews, including unapproved ones by default (same as the panel). Pass approved_only to match what is actually published on the booking page.
| Name | Required | Description | Default |
|---|---|---|---|
| apartment_id | No | Restrict to one apartment. Must belong to this account. | |
| approved_only | No | Only published (moderator-approved) reviews. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context by explaining the default includes unapproved reviews and that approved_only aligns output with the booking page. This goes beyond structured fields.
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 concise sentences with no wasted words. The key default behavior is front-loaded, and the parameter guidance follows naturally.
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 read-only list tool with fully documented parameters and an output schema, the description covers the essential behavior. Nothing critical is missing for an agent to select and invoke it correctly.
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 already documented. The description adds value by clarifying the default state and the practical effect of approved_only, giving the agent semantic understanding beyond the schema text.
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?
States a specific verb and resource: listing guest reviews. It also clarifies the default scope (including unapproved ones) and contrasts with published reviews, which distinguishes this tool from what one might assume about a review list. Clear and unambiguous.
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?
Gives clear context on default behavior and instructs the agent to pass approved_only to match published reviews. It does not name alternatives, but no direct sibling reviews tool exists, and the guidance is sufficient for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify the account behind this token. Works with any valid token regardless of scope — call it first to confirm the connection and see which account (slug, status, owner e-mail) you're talking to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavior beyond those hints: it works with any valid token regardless of scope, and it surfaces account identity details (slug, status, owner email). It does not fully expand on the output schema, but that schema is present separately.
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 filler. The core purpose is front-loaded, then the 'call it first' usage note and output fields follow naturally. Every word earns its place.
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 zero-parameter, read-only introspection tool, the description covers what it does, when to call it, what it accepts (any valid token), and what the response contains. The existing output schema covers the rest, so nothing important is missing.
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?
There are zero parameters and the schema confirms this (empty object). The description usefully clarifies that the token comes from the auth context rather than a parameter, saying 'before this token' and 'any valid token.' That exceeds the baseline for a parameterless tool.
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 starts with a specific verb 'Identify' and a clear resource ('the account behind this token'), which is unambiguous and distinct from the sibling tools that handle apartments, availability, and reservations. It also telegraphs the output (slug, status, owner email), making the tool's purpose unmistakable.
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 explicit usage guidance: 'call it first to confirm the connection.' Since none of the sibling tools overlap with account-identity introspection, no alternative is necessary. This is the standard preflight/health-check invocation pattern.
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.
get_availabilityget_pricingget_reservationget_statslist_apartmentslist_blockslist_reservation_messageslist_reservationslist_reviewswhoami