Hostaway MCP by usefulapi

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

readOnlyHint=true already covers the safety profile, but the description reinforces it with 'nothing is booked or held,' which is meaningful disambiguation against the write siblings. It adds no detail on auth, rate limits, or error cases (e.g., unavailable dates), so it stops short of a 5.

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?

Three short clauses with zero padding: what it does, what it is not, and the underlying endpoint. The atomic constraint ('nothing is booked or held') is front-loaded where an agent will see it.

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 no output schema, the description usefully lists the return breakdown (base rate, cleaning fee, taxes, discounts), and all parameters are schema-documented. Minor gaps remain on failure modes and whether the response includes per-night detail.

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 all six parameters (including markup and reservationCouponId) are documented in the schema. The description adds no parameter-level guidance beyond naming the returned cost components, so the baseline 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?

States a specific verb and resource ('Calculate what a stay at a listing would cost') and enumerates the returned components. It also distinguishes itself from the booking siblings by declaring 'A calculation only: nothing is booked or held.'

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?

Clearly frames this as a quote-only operation, implying that booking requires a different tool (e.g., hostaway_create_reservation). It lacks an explicit 'use X instead to book' routing sentence, but the when/when-not boundary is unambiguous.

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

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

With only destructiveHint=true from annotations, the description carries meaningful extra context: calendar blocking, channel syncing, that only three channelIds are accepted, and that overbooking protection is always left on. These are real behavioral traits beyond what any structured field discloses.

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?

Four tight sentences, front-loaded with the purpose, then constraints, pricing dependency, and behavioral note. Nothing is redundant and the endpoint reference is compact. 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 28-param mutation tool with 100% schema coverage and no output schema, the description covers side effects, the pricing dependency, and channel restrictions well. It omits any mention of failure modes or required-field emphasis, which is a minor gap given the move to the schema's required list.

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 the baseline is 3. The description adds genuine semantics beyond the schema for totalPrice (compute it via hostaway_calculate_price and pass the total) and restates the channelId constraint. Only one parameter gets added meaning, hence 4 rather than 5.

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+resource ("Create a new reservation on a listing") and immediately qualifies scope with the side effects (blocks the calendar, syncs to connected channels). The verb distinction (create vs. the sibling update_reservation/get_reservation) makes the intent unambiguous without opening any 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?

Gives a concrete workflow dependency: "To price it correctly, call hostaway_calculate_price first and pass its total as totalPrice." It also constrains valid channelId values. It stops short of explicit when-not guidance (e.g., when to use update_reservation instead), 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.

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

Annotations only declare destructiveHint=true, so the description carries the rest of the burden. It discloses the mutating nature and the backing endpoint (POST /v1/tasks) and enumerates the optional relationships it can establish, but says nothing about permissions, idempotency, or what is returned on success. Useful context, but not rich behavioral disclosure.

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 and examples, then the endpoint reference. Efficient with no wasted filler, though the endpoint note earns less than the first sentence.

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 15-parameter mutation with no output schema and only a single annotation, the description gives a decent map of what can be set but omits the required 'title' emphasis, handling of the mutually relevant listing/reservation pairing, and any failure behavior. Adequate but with clear gaps given the tool's complexity.

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 all 15 parameters are already documented in the schema (including the category code mapping and date formats), which sets the baseline at 3. The description's summary of tie-to-listing/reservation, assignee, time window, category and cost adds orientation but no semantics beyond what the schema 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?

States a specific verb and resource ('Create an operational task') and immediately grounds it with concrete examples (cleaning after checkout, maintenance job). This distinguishes it cleanly from the sibling hostaway_update_task and hostaway_list_tasks.

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 examples ('cleaning after a checkout or a maintenance job') imply when the tool is appropriate, and the optional scoping to a listing/reservation signals the intended context. However, there is no explicit routing guidance, e.g. when to use create_task versus update_task, or prerequisites like needing an existing listingMapId.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuine behavioral context by enumerating the returned per-day fields and the status vocabulary, and by explaining that includeResources surfaces the occupying reservations. With no output schema, this disclosure carries real weight. No auth/permission or timezone caveats, hence not a 5.

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 dense sentences plus the underlying endpoint reference; the returned-field list is front-loaded before the optional-parameter tip. No filler, no restatement of the title.

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 no output schema, the description must describe returns and it does so field-by-field (status, price, min/max stay, CTA/CTD, notes) including the includeResources expansion. All four parameters are either explained or covered by the schema, so nothing an agent needs to invoke it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema for includeResources — the schema only says 'attached sub-resources' while the description clarifies it reveals the reservations occupying each day. It also documents the status values that appear in results. startDate/endDate/listingId meaning is left to 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?

States a specific verb+resource ('day-by-day availability and pricing for one listing over a date range') and enumerates exactly what each day contains: status, nightly price, min/max stay, closed-to-arrival/departure, notes. This clearly separates it from hostaway_get_listing (property metadata) and hostaway_update_calendar (mutation), so the agent can route without opening schemas.

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?

Clear context: use it for a single listing's day-by-day availability/pricing across a date range, and the conditional 'Set includeResources to see the reservations occupying each day' tells the agent when to flip that flag. No explicit when-not or named alternative (e.g., update_calendar for writes) is given, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds value by enumerating the payload contents (house rules, amenities, fees, taxes, cancellation policy, door code, wifi) and cites the underlying endpoint. It stops short of noting auth requirements or behavior when the id is invalid.

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?

One front-loaded sentence with an endpoint citation tacked on; every clause earns its place and nothing is padded.

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 no output schema, the enumerated field list usefully compensates for the missing return-value documentation. A note on failure behavior for a missing id would make it fully 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?

Schema description coverage is 100%, so both parameters are documented structurally; the description only reinforces that lookup is by id and says nothing about includeResources or the sub-resources it pulls in. Baseline 3 is appropriate given the schema does the work.

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 ('Fetch a single listing by id') and enumerates what the response contains, so an agent can distinguish it from hostaway_list_listings without opening either 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 'by id'/'single' phrasing implies the use case versus the list sibling, but there is no explicit when-to-use or when-not-to-use guidance and no mention of an alternative tool. Usage is inferable rather than stated.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower; the description goes further by enumerating what the statement contains (generated filter, per-reservation financials, grand totals, expenses, owner/PM details), which is valuable given there is no output schema. It omits pagination, auth, or rate-limit notes, but the return-content disclosure is substantive.

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?

A single front-loaded sentence followed by the raw endpoint reference. No filler; the returned-data enumeration is the meat and 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 single-resource read with one fully documented parameter and a readOnly annotation, the description supplies the missing return-content detail the absent output schema would otherwise have to carry. Nothing needed to call it correctly 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?

One parameter at 100% schema coverage, so the schema already documents ownerStatementId. The description adds only that the statement is fetched by that id, contributing no format or constraint detail beyond the schema. Baseline 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?

States a specific verb ('Fetch one'), the resource ('owner statement'), and scope ('one') that cleanly separates it from the list_owner_statements sibling. An agent can identify the operation 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 singular 'one' plus the required id imply a by-ID retrieval distinct from listing, but there is no explicit when-to-use, prerequisite, or exclusion guidance. Usage is only inferred from context and sibling names.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real value by disclosing the returned field set (guest contact details, door code, payment state, cancellation policy) and the underlying REST endpoint. No auth or rate-limit context, but the payload disclosure is genuinely additive given there is no output schema.

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?

One front-loaded sentence that pairs the action with the returned fields, plus a compact endpoint reference. No filler or restated name/title.

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 single-parameter read tool with no output schema and read-only annotations, enumerating the return contents closes the main gap an agent would face. Nothing needed to call it correctly appears to be 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?

Schema coverage is 100% and the single parameter is fully documented in the schema. The description only echoes 'by its Hostaway id' without adding format or constraint detail, so the baseline 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?

States a specific verb ('Fetch'), resource ('a single reservation'), and keying method ('by its Hostaway id'), and enumerates the returned content. The word 'single' implicitly distinguishes it from hostaway_list_reservations and the fetch-vs-mutate distinction separates it from hostaway_update_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 requirement of a known Hostaway id implies the usage context, but the description never names alternatives such as hostaway_list_reservations or states when-not to use this tool. Usage is inferable but not explicit.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context by specifying the return fields (previous and new value, timestamp, user) and the sort order (most recent first), which is valuable especially with no output schema. It does not, however, describe pagination behavior or any limits beyond what the schema already provides.

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 are used efficiently: the first defines the audit trail and its fields, the second gives a use case, and the endpoint is appended compactly. The content is front-loaded with the core purpose and has no wasted text.

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 tool with no output schema and full schema parameter coverage, the description provides enough detail about what is returned and in what order. Combined with the readOnlyHint annotation and parameter constraints, an agent has all the information needed to call 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 description coverage is 100%, so all three parameters (reservationId, limit, offset) are already documented in the input schema. The description only reiterates reservationId in the endpoint path and adds no additional meaning, so the 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?

The description states a specific resource (audit trail for one reservation) and the exact contents (every field change with previous and new value, when, and by which user), which clearly distinguishes it from sibling tools like get_reservation or update_reservation. An agent can identify this as the change-history endpoint 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?

It gives a clear usage context: 'Useful for ‘who changed these dates / this price?’.' However, it does not name alternatives or state when not to use this tool versus get_reservation or update_reservation, leaving some inference to the agent.

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

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

Annotations only declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: which fields come back, and the non-obvious default that only sent messages are returned unless includeScheduledMessages is set. It does not mention pagination behavior or ordering.

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 plus an endpoint reference, with the returned payload front-loaded and the default-vs-opt-in behavior following. No redundant restatement of the tool name or title.

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 no output schema, the description compensates by naming the returned fields and the default filtering behavior, and the schema handles pagination. Missing only minor operational detail such as ordering or result-size expectations for a single-conversation read.

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 all four parameters; baseline is 3. The description adds slight value by spelling out what includeScheduledMessages surfaces ('scheduled, paused or failed'), but says nothing about limit/offset semantics.

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 ('messages in one guest conversation') and enumerates the returned content (body, direction, channel type, send status, timestamps). The scope is clearly narrower than the sibling hostaway_list_conversations, so an agent can distinguish them without opening either 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 default filter behavior and the includeScheduledMessages escape hatch give conditional usage guidance for one parameter. However, there is no routing guidance relative to siblings (e.g., hostaway_list_conversations to discover an id, or hostaway_send_message to reply) and no stated prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful content context — that each record bundles the latest message and linked reservation, and spans channels — plus the underlying Hostaway endpoint, but says nothing about pagination defaults, ordering, or result limits.

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 tight sentences, front-loaded with the core purpose, followed by the filter capability and the backing endpoint. No redundant restatement or padding.

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 no output schema, the description steps in to say what each returned conversation contains, which is the key thing an agent needs to decide relevance. It lacks pagination/ordering notes and explicit sibling routing, so it falls just short of fully 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?

Schema coverage is 100%, so all four parameters are already documented in the schema. The description only reinforces reservationId ('Filter to one reservation') and says nothing about limit/offset/includeResources beyond what the schema states, making the baseline 3 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?

States a specific verb and resource ('List guest conversations') and clarifies what a conversation is (unified inbox across channels) with its payload shape (latest message + linked reservation). This clearly distinguishes it from hostaway_list_conversation_messages, which would return the message thread rather than the conversation list.

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 via 'Filter to one reservation' and the inbox framing, but never states when to choose this tool over hostaway_list_conversation_messages or hostaway_get_reservation. No when-not guidance or alternatives are named.

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

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

Annotations only declare readOnlyHint=true; the description adds the sign convention that governs how results must be interpreted (negative = expense, positive = extra) and enumerates the fields carried back (date, concept, categories, owner statements). It omits pagination/ordering behavior, which matters for a list endpoint with limit/offset.

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?

One front-loaded sentence carrying the core semantics, followed by a short endpoint pointer. No wasted clauses, though the raw endpoint annotation adds little for an agent choosing a 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?

With no output schema, the description usefully compensates by naming the returned fields and the owner-statement linkage, and annotations cover the read-only safety profile. The main gap is pagination/result-volume behavior for a list 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 100%, so limit and offset are already fully documented (ranges, semantics) in the schema. The description adds no parameter-level guidance such as default page size or how to page through large result sets, so baseline 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?

Specific verb (List) + resource (expenses/extras) with an explicit domain distinction: expenses are negative amounts and extras are positive amounts, recorded against listings and reservations. No sibling tool covers this resource, so no alternative needs to be named, but the description stops short of routing language.

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?

Usage is only implied by the domain context: the tool surfaces expense/extra records, including those appearing on owner statements, which suggests when an agent would want it. There is no explicit when-to-use, no exclusions, and no note that results are unfiltered or paginated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's extra job is to add context — and it does: it discloses the shape of what comes back (property attributes) and the API endpoint (GET /v1/listings). It does not contradict the annotation and adds real value beyond it, though it says nothing about pagination behavior or limits for large portfolios.

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?

Three tight sentences: purpose and returned fields first, filter/dimension capabilities second, API endpoint last. No filler, and the most decision-relevant information is front-loaded; slightly dense in the middle sentence but every clause 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 12-parameter, zero-required list tool with no output schema, the description compensates well by describing the returned fields and the filter surface. The main gap is pagination (limit/offset) and result-ceiling guidance, which the agent only learns from the schema.

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 baseline is 3. The description helpfully maps its filter prose onto the parameters (name/city/country/property type/availability dates/guest count/active-archived), but adds no syntax, format, or combined-filter semantics beyond what the schema already documents.

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 ('List the account's properties (listings)') and even enumerates the fields returned (name, address, capacity, base price, fees, check-in times), which goes well beyond restating the name. However, it never distinguishes itself from the sibling hostaway_get_listing, leaving the agent to infer the difference between listing many vs. fetching one.

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 enumerated filters imply when this tool is useful (filtering a portfolio of properties by city, country, availability, guest count, status), but there is no explicit when-to-use statement and no named alternative such as hostaway_get_listing for single-property retrieval. Usage must be inferred from the filter list rather than being stated.

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

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

Annotations already declare readOnlyHint=true, lowering the bar. The description still adds meaningful context by disclosing the return shape (id and name) and the underlying endpoint GET /v1/ownerStatements. It omits pagination/limit behavior, which keeps it from a 5.

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 the purpose front-loaded and no padding. The trailing 'Hostaway: GET /v1/ownerStatements' is marginally redundant for an agent but is compact and useful for API mapping.

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 list tool with no output schema and readOnlyHint coverage, the description supplies the essentials: what is listed and what each record contains. Pagination behavior and result-size expectations are the only notable omission.

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 has zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond confirming the call takes no filtering input.

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 ('List') and resource ('owner statements') scoped to the account, plus what each entry contains (id and name). The plural 'List' vs the singular sibling hostaway_get_owner_statement implies the distinction, but the description never names that sibling explicitly, so it falls short of a 5.

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?

Usage is only implied: an agent can infer this is the enumeration call and hostaway_get_owner_statement is the single-fetch call. There is no explicit when-to-use, no exclusion, and no statement about whether to prefer a filtered alternative.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real context: default sort is newest first, large result sets must be paged via the afterId cursor, includeResources is transmitted as includeResources=1, and dateType only works on accounts with the new reservations query. It stops short of mentioning rate limits or response size limits.

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?

Front-loaded with purpose, then filters, then pagination, then the channel-id legend. The channel enumeration is long but earns its place because the schema has no enum for channelId. No filler sentences.

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 23-parameter read tool with no output schema, the description covers purpose, filterable dimensions, sort default, pagination cursor mechanics, and the out-of-schema channel-id values. The absence of an output schema is partly offset by naming the returned fields; only rate/size limits are unaddressed.

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 the baseline is 3, but the description adds meaning the schema lacks: the concrete channel-id mapping (2000 direct, 2018 airbnbOfficial, 2002 Vrbo, 2005 bookingcom, etc.) for a channelId parameter that has no enum in the schema, plus the note that afterId causes offset to be ignored. That is genuine value beyond the structured fields.

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+resource ('List reservations across all channels') and enumerates the payload fields returned (guest, dates, status, price, channel) and the filter dimensions, so the agent knows exactly what this tool produces. It does not explicitly contrast itself with the sibling hostaway_get_reservation, but the plural/list semantics make the distinction clear.

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?

It describes what can be filtered and how to page ('for large accounts page with afterId'), which is operational guidance, but it never names an alternative tool or states the condition under which this list tool should be chosen over hostaway_get_reservation or hostaway_list_conversations. Usage is implied rather than prescribed.

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

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

readOnlyHint=true already establishes this as a safe read, so the description's main added value is the underlying endpoint (GET /v1/reviews) and the shape of the returned review content. It does not mention pagination behavior, result caps, auth requirements, or rate limits, leaving meaningful behavioral context undisclosed.

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?

Three compact sentences: content returned first, then filter dimensions, then the API mapping. No filler and nothing repeated from the schema.

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 no output schema, the description usefully describes the returned fields (rating, public review, private feedback, host reply), which an agent would otherwise not know. Combined with the fully documented 16-parameter schema, it is nearly complete; only pagination/limit semantics of the response are unaddressed.

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 every parameter (including enums for type, statuses, sortBy and the date bounds) is already documented. The description's filter list is a thematic summary rather than new syntax or format detail, so the baseline 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?

The description states a specific verb (List) and resource (reviews), enumerates the review directions and payload fields (rating, public review, private feedback, host reply), and lists the filterable dimensions. No sibling tool lists reviews, so it can't be confused with any other tool in the set.

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?

It implies usage by enumerating what can be filtered (listings, reservation, type, status, rating range, dates, guest name, host reply), which tells the agent this is a filtered retrieval tool. However, it states no when-to-use conditions, no prerequisites, and names no alternatives, so guidance remains implicit.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds useful context that tasks carry assignee/status/cost and that it maps to hostaway GET /v1/tasks, but says nothing about pagination behavior or default ordering beyond what limit/offset in the schema imply.

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?

Front-loaded with purpose, then filters, then endpoint - three compact sentences with no redundancy. The trailing 'Hostaway: GET /v1/tasks' adds little operational value but is brief enough not to hurt.

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 10-parameter, all-optional read tool with no output schema, the description covers what is returned and what can be filtered, which is enough to invoke it correctly. Minor gaps remain around result volume/paging expectations, but the schema carries limit/offset.

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 baseline is 3. The description groups the four oddly named date parameters into 'start/deadline windows', which lightly clarifies intent, but it adds no syntax or format detail beyond what the parameter descriptions already provide.

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 (List) and resource (operational tasks: cleaning, maintenance, check-in/out), and even enumerates the fields returned (assignee, status, time window, cost). This clearly separates it from sibling hostaway_create_task and hostaway_update_task without needing their schemas.

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 tells the agent which filters are available (reservation, status, text match, channel, start/deadline windows), which implies usage, but never states when to reach for this tool versus alternatives such as hostaway_get_reservation or hostaway_list_reservations. Usable but leaves selection to inference.

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

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

Annotations only carry destructiveHint=true, and the description goes well beyond it: immediate delivery, no recall, no attachment support, a 30-messages-per-minute rate limit, and the default delivery channel. The irreversibility statement directly and consistently reinforces the destructive hint, which is exactly the behavioral context an agent needs before sending.

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?

One dense but well-ordered sentence leads with the irreversible effect, then delivery methods, limitations, rate limits and endpoint. Every clause carries information an agent would otherwise have to guess at.

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 three-parameter mutation with no output schema, the description covers the safety-relevant behavior (irreversibility, rate limit, attachment restriction) and how delivery is chosen. It stops short of saying what happens on failure or what the response contains, but nothing critical to correct invocation 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?

Schema description coverage is 100%, so all three parameters are already documented, including the email default for communicationType. The description mainly restates delivery options and adds only a small clarification ('booking channel'), so the schema does the bulk of the work and baseline 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?

States a specific verb and resource — 'Send a message to the guest in a conversation' — which is distinguishable from the read-oriented sibling hostaway_list_conversation_messages without opening either schema. It also names the exact Hostaway endpoint, removing any ambiguity about which operation is being invoked.

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 this tool applies (you have a conversationId and want to reach the guest) and explains delivery channel options, but it never states when NOT to use it or names an alternative tool. A user wanting to read prior messages has to infer that from context rather than being routed to the sibling list tool.

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

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

Annotations only provide destructiveHint=true. The description adds meaningful behavior beyond that: changes are 'pushed to every connected channel' (a cross-system side effect), the isAvailable=false block semantics, and the multi-unit 0-blocks rule. Rate limits or permission requirements are not covered.

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 dense sentences that front-load the effect ('pushed to every connected channel') and end with the underlying endpoint. Efficient, though the field enumeration is packed tightly.

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 destructive mutation with no output schema, the description explains what is modified, the scope of propagation, and the single-vs-multi-unit distinction. Missing only failure/validation behavior, which is minor here.

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 baseline is 3. The description goes further by explaining the mutual exclusivity of isAvailable vs desiredUnitsToSell for multi-unit listings and the blocking semantics of 0/false, which the schema alone doesn't make as explicit.

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+resource (change availability/pricing for a date range on one listing) and enumerates the exact settable fields. It is clearly distinguishable from read-oriented siblings like hostaway_get_calendar and hostaway_calculate_price.

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 for use and even a conditional branch: multi-unit listings should use desiredUnitsToSell instead of isAvailable. It lacks explicit when-not-to-use guidance (e.g., don't use for single-date reads), so it stops short of full routing.

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

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

Adds real behavioral context beyond the destructiveHint annotation: partial-update semantics, an immutable field (listing), an explicit statement that cancellation and repricing are out of scope, and a non-obvious warning that channel-driven date changes may be overwritten. It omits permission/auth requirements and any indication of what the response contains, so it is not a full 5.

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?

Three tight sentences plus the endpoint reference, with the core action and the most important constraint (partial update) front-loaded. Every sentence carries a distinct fact: scope, patch behavior, restrictions/caveats.

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 25-parameter mutation tool with no output schema and only destructiveHint for annotations, the description covers scope, partial-update behavior, and the key traps (immutable listing, channel overwrite). What remains thin is error/permission behavior and confirmation of what a successful partial update returns, which 25 params of write surface would benefit from.

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 already 100%, so the baseline is 3, and the description earns an extra point by clarifying patch semantics (only send changed fields) and by stating that listing cannot be modified, which constrains what the caller should pass. It does not explain field interactions (e.g., adults/children vs numberOfGuests, arrival/departure pairing).

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?

Specific verb + resource ('Change fields on an existing reservation') followed by an enumerated scope of what can be changed (guest details/counts, dates, check-in/out hours, door code, notes). It explicitly separates itself from create_reservation ('existing') and from cancel/repricing tools, so an agent can place it 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?

Gives clear patch semantics ('Send only the fields to change') plus explicit exclusions ('the listing cannot be changed', 'never cancels or reprices a booking') and a caveat about channel overwrites. It stops short of naming a sibling tool to use for the excluded operations (cancellation/repricing), so 4 rather than 5.

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

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

Annotations carry destructiveHint=true, so the agent is warned this is a mutating operation. The description adds useful context ('send only fields to change') but does not disclose reversibility, what happens to fields not sent, permission/auth requirements, or whether the update is idempotent – gaps that matter for a destructive update with no output schema.

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?

One dense sentence plus a short operational hint. Front-loaded with the verb and scope, zero filler, and the endpoint reference is compactly placed at the end.

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 17-param destructive update with no output schema, the description covers purpose, usage hint, and endpoint. It falls short on mutation semantics (reversibility, unsent-field behavior, auth) but schema coverage at 100% compensates for parameter documentation, making this nearly 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?

Schema description coverage is 100%, so all 17 parameters are already documented in the schema. The description names status, reassignment ('assigneeUserId' by implication), window ('canStartFrom'/'shouldEndBy'), and resolution note, which adds modest mapping value but no syntax or format detail beyond what the schema provides. 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 opens with a specific verb+resource ('Update a task') and enumerates the concrete kinds of changes (status, reassignment, window, resolution note), which distinguishes it clearly from hostaway_create_task and the sibling update tools (update_calendar, update_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?

It gives a clear usage cue – 'Send only the fields to change' – which tells the agent this is a partial-update (PATCH-like) operation. It does not name alternatives or state when not to use it, but the PUT endpoint and field-change instruction provide actionable context.

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