Hostfully MCP by usefulapi

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

readOnlyHint=true already covers the safety profile, and the description reinforces it consistently with 'Computes only — creates nothing'. Disclosing the underlying endpoint (POST /api/v3.3/quotes) is useful context given the POST verb despite read-only behavior. It does not say whether the quote is persisted, whether it expires, or what currency it returns.

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, zero filler: the pricing breakdown and scope come first, the read-only constraint second. 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?

There is no output schema, and the description compensates by enumerating the returned cost components (rent, fees, taxes, deposit, total) — a real gain. It stops short of currency, tax handling, or quote validity, which an agent pricing a stay might want, 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 8 parameters (including lead_uid, pet_count, agency_uid) are already documented in the schema. The description's 'for the given dates and party' only loosely gestures at check_in/check_out/guests and adds no format or default information beyond what the schema provides, 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 (price/quote) and resource (a prospective stay), and enumerates exactly what is computed: rent, fees, taxes, security deposit and total. 'Computes only — creates nothing' differentiates it from the write siblings (hostfully_create_lead, hostfully_create_job) without the agent needing to read 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?

Implied usage is clear — use it to price a prospective stay before booking — and 'creates nothing' implicitly warns against treating it as a booking path. However, no explicit when-not and no named alternative (e.g. hostfully_get_pricing_periods for raw rate periods, hostfully_create_lead for persisting a quote context), so routing is left 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 declare destructiveHint=true, so the description must carry the rest of the burden. It usefully discloses that times are property-local and that the lead tie is optional, but says nothing about auth/permission needs, what happens on a scheduling conflict, or whether an existing job is overwritten. Adds real value but leaves meaningful behavioral gaps.

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 sentences, front-loaded with the core action, followed by the UID prerequisite and the raw endpoint. Every sentence earns its place with no 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?

For a 7-parameter create tool with no output schema, the definition covers the essential call prerequisites (required fields, service UID source, property-local time). It omits any indication of what the call returns (e.g. the new job's UID) and conflict/error behavior, which is a minor but real gap.

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 already 86%, so the baseline is 3. The description goes beyond the schema by stating that "Times are property-local" — a timezone semantic the schema's format description does not convey — and by clarifying that lead_uid is optional. It does not explain the status enum or notes, but that is not required given 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?

States a specific verb and resource ("Schedule a job") and immediately disambiguates with examples ("a cleaning or a guest greeting") plus the objects it acts on (service at a property, optionally a lead). An agent can distinguish this from hostfully_create_lead, hostfully_list_jobs, and hostfully_update_lead 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 prerequisite chain: use hostfully_list_services to obtain the service UID before calling this. Clear context for when the tool applies, but it does not state exclusions (e.g. how this differs from updating an existing job or what happens if a job already exists for that service/property).

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 substantial context beyond the destructiveHint annotation: it discloses that NEW does not confirm a booking or take payment, that blocks are later removable in Hostfully, that inquiries flow through the pipeline, and that dates are property-local. It does not fully explain the destructiveHint flag or what the create returns, but the side-effect profile is well 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?

Five short, front-loaded sentences that each carry information – mode semantics first, then side effects, then date locality, then endpoint. Dense but no filler; slightly heavier than strictly necessary 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 create tool with no output schema and full parameter coverage, the description gives an agent enough to call it correctly and understand consequences. It omits what the response contains (e.g. the created lead identifier), which matters given siblings get_lead/update_lead, but otherwise 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 baseline is 3, but the description adds real meaning: it maps each status value to a distinct behavior and clarifies that dates are local to the property. This ties the status enum to downstream consequences the schema alone only sketches.

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 a lead at one property') and then splits the operation into its two distinct behaviors (BLOCKED vs NEW). An agent can distinguish this from hostfully_update_lead and hostfully_search_leads 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?

Clearly explains the two modes and their consequences – blocks put an owner/maintenance block on the calendar, inquiries enter the normal pipeline without confirming a booking or taking payment. It stops short of naming when to prefer this over a sibling (e.g. create_job or update_lead), so no explicit alternative 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by enumerating the payload contents (status, channel, dates, guest information, notes, assignee) and mapping to the concrete Hostfully endpoint GET /api/v3.3/leads/{leadUid}, which helps an agent anticipate the response shape 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?

A single dense sentence that front-loads the verb and scope, plus a short endpoint reference. No filler; each clause (lead subtypes, returned fields, API path) carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-record read with readOnlyHint and no output schema, the description supplies the returned-field inventory and API mapping, which is enough for correct invocation. It omits only edge behavior such as what happens when the UID matches no lead.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (lead_uid) and schema description coverage is 100%, so the schema already carries the semantics and the baseline is 3. The description restates 'by UID' without adding format, source, or retrieval guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch) and resource (one lead) with scope qualifier 'by UID', then disambiguates the domain term by enumerating what a lead can be (booking, inquiry, booking request, block). An agent can distinguish this from create_lead, update_lead, and search_leads from the description alone.

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 UID' phrasing implies retrieval of a single known record versus a search, but the description never explicitly names hostfully_search_leads as the alternative or states when to prefer one over the other. Usage is inferable but not spelled out.

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 main added value is disclosing the payload contents (price, min stay, availability per date). It says nothing about pagination, response size, date-range limits, or auth requirements, which is a moderate gap for a read tool with annotations covering safety.

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, front-loaded with the returned data rather than the HTTP verb, and the endpoint reference is a useful tail rather than a lead. Phrasing is slightly convoluted ('the ... set for each date of one property over a range') but wastes no space.

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 three required params, full schema coverage, and no output schema, the description partially compensates by naming the returned fields. It still omits response shape and pagination behavior, but for a simple range read it is close to 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 property_uid, from and to are already documented with their YYYY-MM-DD formats. The description reinforces that the range is per-property but adds no format, ordering, or boundary semantics 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 resource (pricing periods) and enumerates the returned fields — nightly price, minimum stay, check-in/check-out availability — scoped to one property over a date range. Clear enough to distinguish from list_* siblings, though it does not explicitly contrast with the nearest sibling hostfully_get_property_calendar.

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?

No when-to-use guidance, no exclusions, and no routing to alternatives such as hostfully_calculate_quote or hostfully_get_property_calendar. The date-range scope is implied by the description but not framed as a usage condition.

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 readOnlyHint=true annotation already declares the safe-read profile, so the bar is lower; the description adds real value by enumerating the data domains returned (pricing/availability settings, channel data, cancellation policy) and mapping to the underlying endpoint GET /api/v3.3/properties/{propertyUid}. It does not mention error behavior for an unknown UID, which is the main remaining gap.

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 covering the resource and its contents, plus a compact endpoint reference. No filler and no repetition of structured fields.

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?

There is no output schema, and the description compensates by enumerating the returned fields, so an agent knows what to expect from the response. For a single-param read tool this is nearly complete; only error/not-found behavior is 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents property_uid; baseline 3 applies. The description adds no syntax, format, or lookup guidance beyond what the schema and path template already convey.

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') and resource ('one property's full details') and enumerates the payload contents (address, time zone, rooms, pricing, availability, channel data, booking notes, cancellation policy). This clearly distinguishes it from sibling hostfully_list_properties (many) and hostfully_get_property_calendar (calendar slice).

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 implied by the name and the 'one property' scoping versus the list sibling, but the description never states when to prefer this tool over hostfully_list_properties or hostfully_get_property_calendar, nor any prerequisites. Adequate but leaves the routing decision 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?

readOnlyHint=true already establishes this as a safe read, and the description is consistent with that. It adds the underlying endpoint (GET /api/v3.3/property-calendar/{propertyUid}) but discloses nothing about response shape, pagination, or date-range limits beyond what the annotations and schema carry.

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: the first front-loads the purpose and value proposition, the second supplies the API mapping. Nothing is padded, though the endpoint reference serves the implementer more than the agent.

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 carries the burden of return-value signaling and does so by declaring day-by-day availability and pricing granularity. That is adequate for a simple read tool, though it omits anything on date-range bounds or result size.

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 from/to/property_uid/availability_comments are already documented in the schema. The description contributes no additional parameter meaning, making the baseline 3 the correct score.

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 names a specific verb and resource — day-by-day availability and pricing for one property over a date range — and frames the intent ('is it free, and at what price?'). It implicitly separates itself from pricing siblings like calculate_quote and get_pricing_periods, though it never names them explicitly.

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 'direct answer to is it free' framing implies when the tool is useful, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many siblings (calculate_quote, get_pricing_periods). Usage is inferred 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the API-key scoping constraint and enumerates what the response contains, which is genuine added context. It does not mention pagination or result-size limits, which is the only gap.

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 that front-load the purpose, then layer on the workflow hint; the endpoint reference is compactly appended. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description carries the burden of explaining returns, and it does so by naming the key fields (UID, currency, check-in/out times). An agent has everything needed to call it and use the result.

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 takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering inputs are needed beyond the API key scope.

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 the agencies') plus scope ('this API key can access') and the returned fields (UIDs, currency, default check-in/out times). No sibling lists agencies, so it is unambiguously distinguishable from hostfully_list_properties, hostfully_list_owners, etc.

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?

'Start here to find the agency_uid other tools need' gives explicit workflow context and tells the agent when this tool is the right entry point. It lacks an explicit when-not clause, but for a zero-parameter lookup with no real alternatives, the guidance is clear and actionable.

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 declares this a safe read, so the safety profile is covered by annotations. The description adds which fields come back, which is useful, but says nothing about pagination, result limits, ordering, or rate limits for what is presumably a large collection endpoint.

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 covering resource and returned fields, plus the underlying API endpoint. Efficient, though the endpoint string is marginally useful to an agent and slightly pads the definition.

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?

A simple read-only list tool with one optional parameter and no output schema; the description compensates for the missing output schema by naming the fields returned. Missing only collection-level behavior (pagination/limits), which is a minor gap.

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 agency_uid parameter is fully documented in the schema (default env var plus pointer to hostfully_list_agencies). The description adds no parameter-level 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 (List) and resource (agency's guest records) and enumerates the returned fields (names, email, phone, address, profile notes). This clearly distinguishes it from sibling list tools such as hostfully_list_owners, hostfully_list_properties, and hostfully_list_agencies.

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 listing intent is implied by the verb and resource, but there is no explicit guidance on when to use this vs other list/search tools, nor any note about prerequisites beyond the schema's default-UID hint. Adequate but with a clear gap.

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. The description adds useful behavioral context — that results are sorted by start date and that property/status narrowing is optional — but says nothing about pagination, rate limits, auth, or result volume.

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 dense sentence that front-loads scope, filters, and sort order. The trailing API endpoint reference ('Hostfully: GET /api/v3.3/jobs') is conventional but adds little for an agent choosing the 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 read-only list tool with full schema coverage and no output schema, the description covers purpose, scope, optional filters, and ordering. It could still note result shape or pagination, but nothing essential for a correct call 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 five parameters (including the modified_since default caveat) are documented in the schema itself. The description only restates the window/property/status filters, adding no format or syntax detail beyond that — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (operational jobs) and even enumerates what counts as a job (cleanings, greetings, maintenance, other services). The date-window scope is front-loaded, easily distinguishing it from hostfully_create_job and other list_* siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies the usage context (jobs scheduled in a date window, optionally narrowed by property and status), but never states when to prefer this over alternatives or what prerequisites exist. Since there is no sibling jobs-list tool, the practical risk is low, but the guidance is only implied.

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 declare readOnlyHint=true, so safety is already covered; the description adds genuinely new behavioral context: 'Cursor-paginated' and the underlying endpoint GET /api/v3.3/messages, which tells the agent this is a paged read against an upstream API. It does not discuss rate limits, ordering, or empty-result behavior, keeping it 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 tight sentences with zero filler: purpose first, scoping instruction second, pagination note third. The endpoint reference is appended compactly rather than expanded into prose.

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?

There is no output schema, and the description compensates by naming the returned fields ('sender type, status and content') and the pagination mechanism. For a 6-param, all-optional read tool with readOnlyHint set, an agent has everything 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%, and each schema description is already specific ('Only messages about this lead.', 'Cursor from the previous page's _paging._nextCursor.'). The description restates the lead/thread/agency scope and pagination but adds no format or interaction detail beyond the schema, so the baseline 3 is right.

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 (read/list) and resource (guest messages) plus the channels covered (Airbnb, VRBO, Booking.com, email, SMS, WhatsApp, in-app) and the three scoping axes (lead, thread, agency). The lead/thread/agency framing implicitly separates it from the sibling hostfully_list_threads and hostfully_list_reviews, so an 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?

'Give lead_uid, thread_uid, or agency_uid (or the default)' makes the scoping choice explicit and tells the agent a fallback exists when no identifier is supplied. It stops short of naming a sibling alternative or stating when not to use this tool (e.g., versus hostfully_list_threads for thread metadata), so it is clear context without exclusions.

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 is a safe read. The description adds a behavioral constraint not present in structured data — that at least one filter parameter is mandatory despite the schema showing zero required parameters — which prevents a runtime error. It omits pagination, result limits, and rate-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first defines the resource and its contents, the second gives the filtering rule and endpoint. Zero waste and front-loaded, with no repeated schema content.

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?

There is no output schema, so the description does useful work by enumerating what an order returns (rent, fees, services, adjustments, taxes, commission, total). For a four-parameter read-only list tool with full schema coverage and annotations, this is close to complete; only pagination/limit behavior is 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 all four parameters (lead_uid, guest_uid, property_uid, updated_since) are already documented in the schema. The description restates the same filter dimensions without adding format, syntax, or exclusivity rules, so the baseline 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?

States a specific verb (List) and resource (orders), then defines what an order actually is — 'the money side of a booking' with its component fields. That definitional framing helps an agent distinguish orders from leads/properties/guests. It does not explicitly name a sibling tool it should be preferred over, so it stops 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?

The description gives the filter dimensions and the hard rule that at least one is required, which implies the contexts in which the tool is usable. However, it names no alternative tool or condition for choosing between this and search_leads, calculate_quote, or the other list tools, so when-to-use vs alternatives is only implied.

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. The description adds value by enumerating what the records contain and naming the underlying endpoint, but omits pagination behavior, result limits, and auth/scoping requirements. With annotations covering safety, a 3 fits.

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 covering scope, returned fields, and the filter, with the endpoint reference appended. Efficient overall, though the raw endpoint string is marginally redundant for an agent.

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 enumerates the returned fields, and annotations handle the safety profile. What remains missing is pagination/result-size behavior, which matters 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 description coverage is 100%, so both parameters are already documented, including the HOSTFULLY_AGENCY_UID default and its pointer to hostfully_list_agencies. The description's 'optionally filtered by a search string' only restates the query param, adding no syntax or matching-semantics detail.

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) plus resource (agency's property owners), with the returned fields named (contact details, business name, commission rate, permissions). No sibling tool lists owners, so the agent can unambiguously select this 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 description notes the search-string filter is optional, which implies the primary context (browse all owners, optionally narrow). But it gives no explicit when-to-use guidance, no prerequisites, and no mention of the sibling tools that serve adjacent needs (e.g. hostfully_list_agencies for the agency UID).

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 cover readOnlyHint, so the description earns credit for disclosing pagination behavior ('Cursor-paginated') and enumerating the returned fields, which matters since no output schema exists. It stops short of noting auth requirements, rate limits, or ordering guarantees.

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 sentences, front-loaded with the core purpose and scope, followed by pagination and endpoint mapping. No filler; every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with no output schema, the description supplies the return-field inventory, the pagination contract, and the agency scope, which is close to sufficient. It lacks field-type or ordering detail but nothing blocks a correct invocation.

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 four parameters (limit, cursor, agency_uid, updated_since) are already documented in the schema at high quality. The description only hints at the agency scoping via 'an agency's properties' and adds no syntax or format detail beyond the schema, 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 (list) and resource (an agency's properties/rentals), and enumerates the fields returned (name, address, type, bedrooms, active flag, pricing/availability). It is clearly a bulk-list operation distinct from hostfully_get_property, though it never explicitly contrasts the two.

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 implied: call this to enumerate an agency's properties, and paginate with a cursor. There is no explicit when/when-not guidance or pointer to alternatives such as hostfully_get_property for a single record. Adequate but with clear gaps.

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 safe-read profile is covered. The description adds a pagination trait ("Cursor-paginated"), but the cursor mechanics are already documented in the schema, and there is no mention of auth requirements, default sorting, or page limits. It adds marginal value beyond the annotations.

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 compact sentences with zero filler: purpose and scope first, returned fields next, pagination and the upstream endpoint last. 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?

With no output schema, the enumerated field list is doing real work to describe what comes back, and pagination is flagged. For an 8-parameter, zero-required list tool it is nearly complete, though defaults, sorting behavior, and whether the two scope filters are mutually exclusive remain unstated.

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 63%, so roughly a third of the parameters (sort, source, sort_direction) are undocumented in both schema and description. The description's "property or a lead" phrasing maps to property_uid/lead_uid, which is a small addition, but it does not explain the sort enums or source filter. 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?

States a specific verb ("List") and resource ("guest reviews") plus the scoping axis ("for a property or a lead"), and enumerates the returned fields. No sibling tool in the list covers reviews, so an agent can select this unambiguously 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?

Implies usage through "for a property or a lead," hinting at the property_uid/lead_uid filters, but never states when to use this over an alternative call or whether both filters can be combined. No explicit exclusions, prerequisites, or alternatives are given.

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 safety is already covered. The description adds real context beyond that: the kinds of services returned, the fields present in results, and the cross-tool dependency on the service UID. It omits pagination and default scoping behavior, keeping 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 front-loaded sentences plus an endpoint reference, with zero filler. The list contents are stated before the create_job linkage, so the most important information comes first.

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?

There is no output schema, and the description partly compensates by naming the returned service attributes. It lacks pagination or scope notes for a list endpoint, but for a three-parameter, all-optional read tool it is close to 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 all three parameters (agency_uid, catered_to, service_provider_uid) are already documented in the schema. The description adds no syntax, defaults, or filtering semantics beyond what the schema states; 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+resource ('List the services an agency offers or schedules') with concrete examples (cleaning, transportation, greeting, cooking, tours) and the returned fields (provider, price, duration). This clearly separates it from sibling list tools like hostfully_list_jobs or hostfully_list_orders.

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 supplies a concrete downstream use case: the service UID is what hostfully_create_job needs, which tells the agent when to reach for this tool. It does not state when not to use it or name an alternative listing tool, so it stops 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 the safety profile is covered. The description adds useful context beyond that: what the results contain (participants, read status) and that results are cursor-paginated. It does not, however, note rate limits or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences that front-load the resource and scope, then parameters, then pagination. The trailing endpoint reference ('Hostfully: GET /api/v3.3/threads') is mild implementation trivia but does not bloat the definition.

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 no output schema, the description covers scope, pagination, and the gist of returned fields. An agent has enough to invoke it, though the lack of tie-breaking guidance against hostfully_list_messages leaves a small gap.

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 75%, so most parameters are self-documented. The description adds only marginal meaning, noting the lead_uid/agency_uid scoping choice and the default fallback; limit and cursor are left entirely 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 ('List guest-messaging threads') with scope ('for an agency or one lead') and return content ('participants and read status'). It is clear, though it does not explicitly differentiate itself from the sibling hostfully_list_messages.

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?

'Give lead_uid, or agency_uid (or the default)' implies how to scope the call but never states when to choose this over alternatives like hostfully_list_messages or how to pick between the lead_uid and agency_uid paths. Usage is implied rather than spelled out.

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 assert readOnlyHint=true, and the description is consistent with that while adding real context: the return contents (status, type, channel, dates, guest info), the cursor-pagination behavior, and the minimum-filter requirement. It stops short of noting rate limits or whether the default agency scope can be broadened.

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 sentences, front-loaded with the domain definition and filter axes, followed by return contents and the invocation constraint. No filler, and the API endpoint reference is compact.

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 enumerating returned fields, and pagination is covered via the cursor parameter. An agent has everything needed to call it correctly; only edge behavior (e.g., max result windows, behavior when both date ranges and UIDs are combined) is unstated.

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 already 100%, so the schema does the heavy lifting, but the description adds semantics the schema lacks: agency_uid silently falls back to a default, and at least one of agency_uid/property_uid/lead_uids must be supplied. That cross-parameter constraint is genuinely beyond the per-field descriptions.

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 (search) and resource (leads), and explicitly defines the domain term: 'Hostfully's word for bookings, inquiries, booking requests and calendar blocks.' It also enumerates the filter axes (agency, property, UIDs, check-in/out), so an agent can distinguish it from hostfully_get_lead or hostfully_create_lead without opening a 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 invocation constraint — 'Give at least one of agency_uid (or the default), property_uid, or lead_uids' — which tells the agent what a valid call looks like. It does not, however, route the agent between alternatives (e.g., when to prefer hostfully_get_lead for a single record), so it stops short of full when/when-not guidance.

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 annotation only carries a boolean destructiveHint; the description converts that into concrete consequence — the message reaches a real guest and cannot be unsent — and instructs the agent to confirm before invoking. It also discloses the channel-scope limitation on DIRECT_MESSAGE, which no annotation covers.

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-load the action and the irreversibility warning, with the channel constraint and the API path trailing as supplementary detail. No filler.

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 an irreversible mutation with no output schema, the description supplies the essential facts: who receives it, the supported modes, the channel restriction, and the irreversibility warning. Return-value details are not needed given no output schema is defined.

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 would be 3, but the description adds meaning beyond the schema by explaining that DIRECT_MESSAGE routes via the booking channel and is limited to Airbnb/VRBO/Booking.com leads, and that the message targets the lead's guest rather than the lead itself.

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 (send) and resource (message to the guest of a lead), and names the two delivery modes (EMAIL / DIRECT_MESSAGE) plus the channel restriction. An agent can distinguish it from hostfully_list_messages or hostfully_list_threads 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?

Gives a clear precondition (Airbnb, VRBO or Booking.com leads only) and an operating instruction (confirm the text first), which is real usage context. It does not, however, tell the agent when to prefer a new message versus posting into an existing thread via thread_uid, or what to do for non-channel leads.

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 supply destructiveHint=true, so the description carries real additional load: it discloses PATCH-style partial-update semantics, that omitted guest fields are preserved, that personal-data fields may be silently dropped by key permissions, and the underlying endpoint. It does not state reversibility or what the response returns, but the mutation behavior is well disclosed.

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, front-loaded with the write scope followed immediately by exclusions and the permission caveat. Every clause (including the endpoint) carries information; 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?

No output schema exists, so the description is the only place return behavior could be described, and it is silent on the response shape. Otherwise it is complete for a partial-update tool: write scope, exclusions, preservation of omitted fields, and permission risk are all covered.

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 50% with four top-level params, and the description enumerates the guest sub-object contents (name, contact, address, arrival/departure times) plus notes and extra notes, mapping each top-level parameter to its purpose. It adds grouping context the schema only partially provides via the nested "Guest fields to change" note.

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 (partially update), resource (a lead), and scope (notes, extra notes, guest details), then explicitly rules out dates, party size, property and status. An agent can distinguish this from hostfully_get_lead, hostfully_create_lead and hostfully_search_leads 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?

The "Does NOT change dates, party size, property or status" clause is explicit when-not guidance, and the permission caveat tells the agent fields may be silently ignored. It stops short of naming which sibling to use for those excluded fields (e.g. a status/date change tool), so it is clear context rather than full routing.

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