OwnerRez MCP by usefulapi

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

Annotations only provide destructiveHint=true; the description adds value by disclosing it is a mutation ('MUTATES OwnerRez data'), the underlying POST /v2/bookings JSON write, and that it returns the created booking. It does not discuss auth requirements or failure/partial-write behavior, but the additions exceed the annotation content.

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-loads the critical fact ('MUTATES OwnerRez data') and packs verb, endpoint, object semantics, the `fields` rationale, and return value into four tight sentences with 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?

With no output schema, the description usefully states it 'Returns the created booking,' and it covers the mutation, endpoint, and object semantics for an 8-param tool. It is largely complete, though auth/permission expectations for the write 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 would be 3, but the description adds meaning beyond the schema by explaining why `fields` exists ('the exact charge/quote shape is account-specific') and that it is merged with typed fields. This contextualizes the flexible-object parameter rather than merely restating it.

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 ('creates a new booking (reservation)') and clarifies the domain object relation ('ties a guest to a property for a date range'). Distinguishes it from siblings like create_quote and create_guest, which also create records but of different types.

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 implied usage: it is the tool to create a booking, and it advises passing account-specific documented fields via `fields`. However, it never names alternatives (e.g. create_quote for pricing) or when-not conditions, so routing guidance is only inferred.

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; the description adds real behavioral context beyond that by naming the endpoint (POST /v2/guests, JSON) and warning that emails/phones/addresses must be passed as arrays of objects via the `fields` passthrough rather than typed parameters. It also notes the return (created guest). It does not cover auth/permission requirements or idempotency, so 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?

Three compact sentences, front-loaded with the mutation warning followed by the endpoint and the non-obvious array workaround, and closing with the return value. 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 a mutation tool with no output schema, the description closes the important gaps: it flags the mutation, gives the endpoint, explains the array passthrough quirk, and states the return value. It omits whether target fields are required or any permission requirements, but nothing critical to calling the tool 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 the baseline is 3, but the description adds meaning the schema lacks: the `fields` passthrough is the way to send array-shaped data, illustrated with a concrete email_addresses example. That clarifies semantics of the otherwise opaque additionalProperties object.

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 ('creates a new guest (contact)') and flags that it mutates OwnerRez data, which immediately separates it from the get_/list_/update_ siblings. 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?

Usage is implied by 'creates a new guest' and the API route is given, but there is no explicit when-to-use vs alternative guidance (e.g., use update_guest for existing contacts, or the array-passthrough constraint applies only at create time). The array handling hint is genuinely useful but is a how-to, not a when-to-use rule.

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 and a title, so the description usefully adds the mutation warning ('MUTATES OwnerRez data'), the HTTP verb/endpoint, the account-specific linkage caveat, and the return behavior. It does not cover auth/permission needs or rate limits, but it adds real context beyond the annotation.

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 clauses with the mutation warning front-loaded, then endpoint, then the linkage caveat, then return value. No filler, though the endpoint notation is arguably schema-adjacent detail rather than agent-critical guidance.

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 'Returns the created message' line correctly covers the return. The mutation is flagged and the tricky nested `fields` escape hatch is explained, which is the main complexity here. Missing only auth/permission expectations for a write call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining why `fields` exists and giving concrete keys (thread_id, booking_id) that the schema only alludes to as 'additional documented OwnerRez fields'. That is genuine additive meaning, though it doesn't describe value formats or limits.

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 (posts) and resource (a message into a guest-communication thread) and also names the underlying endpoint POST /v2/messages. An agent can immediately distinguish this from create_booking, create_guest, send-type siblings, and the list_messages reader.

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 rather than stated: the description explains that thread/booking linkage is account-specific and should be passed through `fields`, which tells the agent how to call it. It never says when to prefer this over list_messages or another write path, and gives no explicit prerequisites or 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?

Discloses mutation semantics ('MUTATES OwnerRez data'), the underlying endpoint (POST /v2/quotes), the account-specific nature of the quote/charge shape, the `fields` escape hatch for that variability, and the return value. Annotations only carry destructiveHint=true, so this adds substantial context beyond structured fields.

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

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

Three tight sentences front-loaded with the mutation warning, then endpoint, then caveat and return. Every sentence earns its place; only the parenthetical gloss is mildly redundant.

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 states it returns the created quote, and it covers mutation, endpoint, and the account-specific field escape hatch. It omits auth/permission requirements and whether quote creation has side effects, which leaves a small gap for a write tool with a nested `fields` object.

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 property_id, dates, guest_id, and counts. The description only restates the `fields` merge behavior that the schema already spells out, adding no syntax or format detail beyond it.

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 ('creates'), resource ('quote'), scope ('for a property + date range'), and even disambiguates the artifact as 'the pre-booking pricing document'. This distinguishes it from sibling create_booking 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 'pre-booking pricing document' framing gives clear context for when this tool is the right call versus create_booking. It does not state explicit exclusions or prerequisites (e.g. property must exist, auth scope needed), 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds that optional related collections can be embedded rather than fetched separately, which is useful behavioral context, but says nothing about auth needs, rate limits, or not-found 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?

Three terse sentences with the core action front-loaded and zero filler. The endpoint and embed note are compact add-ons rather than 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 single read-only fetch with fully covered parameters and annotations declaring the safety profile, this is nearly complete; the embedding hint clarifies the response shape somewhat. The absence of an output schema means return structure is only partly conveyed, which keeps it short of a 5.

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 are already documented in the schema. The description only restates the include_* flags as "opt into embedded charges/guest/tags," adding no syntax or defaults beyond the structured data. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (a single booking) and pins the lookup to an id, which implicitly separates it from the list_bookings sibling. It even names the backing endpoint, GET /v2/bookings/{id}. It stops short of explicitly naming which sibling to use instead for bulk retrieval.

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?

"Opt into embedded charges/guest/tags" implies when to flip the flags, but there is no explicit when-to-use versus list_bookings or get_guest, and no prerequisites or error conditions. 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 underlying endpoint (GET /v2/guests/{id}), which is genuinely useful context, but says nothing about return shape, missing-id/404 behavior, or any rate 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 with the operation front-loaded and the API reference appended. Nothing is wasted and nothing important is buried.

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 one-parameter read tool whose annotations carry the read-only profile, this is nearly sufficient. It falls just short of ideal by not hinting at what a successful lookup returns or how a non-existent id is surfaced.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already documented as 'The guest id.' The description's 'by id' adds no format, range, or lookup 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), resource (guest/contact), and cardinality (single, by id). The word 'single' plus 'by id' cleanly distinguishes it from the sibling list_guests without needing to open 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?

Usage is implied: call this when you have one guest id and want that record. There is no explicit statement of when to prefer this over list_guests, and no exclusions or prerequisites 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 already declare readOnlyHint=true, so the safe-read profile is covered structurally. The description adds the upstream endpoint mapping, useful context, but says nothing about auth requirements, 404/not-found behavior, or what the response contains. With annotations carrying the safety burden, this is an acceptable but thin addition.

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, zero waste, with the core action front-loaded before the API detail. Nothing is padded or redundant.

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 one-parameter read tool with full schema coverage, an existing readOnlyHint, and no output schema, the description supplies everything needed to select and invoke it. Only minor gaps remain, such as error behavior on an invalid or missing id.

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 the single 'id' parameter is documented in the schema as an integer listing id, so the schema does the work. The description adds nothing beyond naming the id parameter, which is the correct baseline.

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 ('a single channel listing'), and explicitly scopes it to one record retrieved by id, which cleanly separates it from the sibling list_listings. The appended API route (GET /v2/listings/{id}) reinforces exactly what it does.

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 id' signals it is for point lookups rather than enumeration, and the existence of list_listings as a sibling makes the split inferable. There is no explicit when-to-use/when-not statement or named alternative, so this is minimum-viable 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context beyond that — it verifies credentials and maps to GET /v2/users/me — but says nothing about auth failure behavior, rate limits, or the shape of the returned user object.

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, fully front-loaded, with the operative purpose first and the API endpoint as supporting detail. Nothing is wasted or buried.

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 tool this is nearly complete: purpose, intent, and endpoint are covered. Since no output schema exists, a brief note on what the user object contains would have closed the only remaining 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly implies no inputs are required (identity comes from the credential).

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 gives a precise verb+resource ("Return the authenticated OwnerRez user") and the parenthetical clarifies the practical intent is credential verification. No sibling in the list shares this purpose, so no differentiation is strictly needed, though it never explicitly contrasts itself with get_guest/list_owners.

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?

"verifies your credentials" implies the classic use case (a cheap auth/sanity check before other calls), but there is no explicit when-to-use, when-not, or named alternative among the many get_* and list_* siblings. Usage is implied 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 tells the agent this is a safe read, so the description's added value is the OwnerRez endpoint mapping (GET /v2/payments/{id}), which is genuinely useful context. It does not disclose error behavior for a missing/invalid id or any rate 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 short sentences, purpose stated first, no filler. The endpoint clause is compact and arguably earns its place by mapping to the underlying API.

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 one-parameter read tool with annotations covering the safety profile and no output schema to explain, this is nearly complete. Only the lack of any alternative-routing hint keeps it from the top score.

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 the single parameter is fully documented as 'The payment id.' The description's 'by id' adds no syntax, format, or constraint beyond the schema, 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 (fetch) and resource (a single payment) and identifies the identifier used. The word 'single' implicitly separates it from list_payments, but the sibling is never named, so an agent must still infer the routing.

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?

There is no explicit when-to-use or when-not-to-use guidance. The description implies you need a known payment id, but it never contrasts with list_payments, which is the natural alternative when the id is unknown.

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 value beyond that by noting the response 'includes time_zone' and mapping to the underlying API endpoint GET /v2/properties/{id}, which with no output schema is genuinely useful behavioral context.

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, front-loaded with the core action and outcome, with the API mapping appended as supporting 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 a simple single-parameter read tool whose safety is declared by annotations, this is close to complete: it names the action, the filter key, one returned field, and the endpoint. The only gap is that it never mentions list_properties as the enumeration alternative.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema documents it fully. The description only restates 'by id', adding 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+resource ('Fetch a single property by id'), and the word 'single' implicitly contrasts with the sibling list_properties. It does not name list_properties explicitly, but an agent can still distinguish 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 only implied: fetching one item by id implies you already have an id, versus list_properties for enumeration. There is no explicit when-to-use or prerequisite statement, so the agent must infer the 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?

The readOnlyHint annotation already tells the agent this is a safe read, and the description adds only the REST endpoint mapping, which is not behavioral context. It says nothing about what happens on a missing/invalid id, permissions, or the shape of a quote beyond the basic read semantics.

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, zero filler, with the core action front-loaded ahead of the endpoint detail. Nothing needs trimming or reordering.

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 one-parameter read tool with full schema coverage, no output schema, and a readOnlyHint annotation, the definition gives an agent everything needed to invoke it correctly. Only minor behavioral detail (error behavior on unknown ids) is absent.

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?

With a single parameter at 100% schema description coverage, the schema already documents id fully. The description only restates "by id," adding no format, range, or lookup semantics 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?

The description states a specific verb (Fetch) and resource (a single quote) scoped by id, which cleanly separates it from list_quotes. It does not explicitly name the sibling it contrasts with, so sibling differentiation is implied rather than stated.

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?

"Fetch a single quote by id" implies the usage condition (you have an id, you want one record), and the contrast with the sibling list_quotes is implicit. There is no explicit when-to-use/when-not or named alternative, leaving usage 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 the safety profile, and the description adds real context beyond it: the upstream endpoint, the opt-in embedding flags, and the pagination envelope ({ items, count, limit, offset, next_page_url }). It stops short of stating rate limits, default page size behavior beyond the schema, 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, no filler, with the resource and endpoint front-loaded and the return shape last. Slightly dense with category lists, but nothing is wasted.

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 13-param read-only list tool with no output schema, the description covers the filter surface, the pagination model, and the response envelope, which compensates for the missing output schema; annotations cover the safety profile. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so every parameter, including the free-form 'params' escape hatch and the include_* flags, is already documented in structured data. The description's summary of filter axes restates that surface rather than adding syntax or edge-case meaning, 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+resource ('List bookings (reservations)'), pins the underlying OwnerRez endpoint (GET /v2/bookings), and enumerates the filter axes and embedded expansions. An agent can distinguish this from get_booking or list_inquiries without opening the schema.

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

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

The description implies when the tool is useful (filtering bookings by property, date window, changed-since, status) but never states when to prefer it over siblings such as get_booking for a single record or list_inquiries. Usage is inferable rather than directed.

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 annotation already establishes this as a safe read, so the bar is lowered; the description adds the backing endpoint (GET /v2/fielddefinitions) and clarifies the semantic scope of what is listed. It adds no auth requirements, rate limits, or pagination behavior beyond what the schema's limit/offset already convey.

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 with the purpose front-loaded and a clarifying parenthetical; nothing is padded. The API-endpoint sentence is mildly redundant with the tool name but earns some place as a mapping hint, so it falls just short of 5.

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-required-param, read-only list tool with full schema coverage, the description is essentially sufficient, and the parenthetical partially compensates for the absent output schema by hinting at what is returned. It could go one step further and describe the returned definition shape or paging expectations.

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 typed limit/offset params and the catch-all params object are already documented in the schema. The description references none of them and adds no syntax or filtering detail, making the baseline 3 correct.

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 (custom-field definitions) and even resolves the ambiguity of that resource with a parenthetical defining it as the schema for custom fields on properties/bookings/guests. It is clearly distinct from siblings like list_properties or list_bookings, but it never explicitly contrasts itself with an alternative, which a 5 would require.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The description only says what the endpoint is; an agent gets no help deciding when this tool is the right call versus fetching the entities themselves.

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 readOnlyHint=true, so the description meaningfully adds behavioral context: the mandatory-parameter requirement and the shape of the response envelope. It still omits auth needs and rate/pagination limits, but goes well beyond the annotation.

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, front-loaded sentences with no filler; the mandatory-parameter constraint and return shape are stated compactly. The endpoint citation is slightly redundant but useful for API-aware agents.

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 definition covers purpose, the key calling constraint, and the return envelope. Remaining gaps (auth, pagination semantics, error modes) are minor.

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 9 parameters (including q/created_since_utc requirements and limit/offset). The description only restates the mutual-requirement, adding little beyond structured fields — 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 clear verb+resource ('List guests (contacts)') and even pins the exact OwnerRez endpoint GET /v2/guests. It does not explicitly name sibling tools like get_guest or create_guest to differentiate scope, but the list-vs-get-vs-create distinction is fairly self-evident from the verb.

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 NOTE gives a hard prerequisite — OwnerRez REQUIRES either `q` or `created_since_utc` — which is a genuinely useful usage condition an agent must satisfy to avoid a failed call. It stops short of saying when to prefer this over siblings such as get_guest for a single contact.

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 the safe read-only profile, and the description reinforces it by naming a GET endpoint. However, it adds nothing about rate limits, auth requirements, or pagination behavior beyond what the annotations and limit/offset schema already convey, so it meets but does not exceed the lowered bar.

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 verb+resource, then the API anchor, then the parameter hint. Nothing is padded or redundant.

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, zero-required-parameter list tool with no output schema, the description covers purpose, endpoint, and the filter escape hatch. Missing only brief guidance on result shape or pagination expectations, a minor gap given the schema documents 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 limit, offset, and params are already fully documented in the schema. The description's note about `params` for documented filters restates the schema's own wording without adding filter names, syntax examples, or escaping rules.

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 inquiries') and disambiguates the resource with a parenthetical gloss ('pre-booking leads') that separates it from list_guests and list_bookings. It also anchors the tool to a concrete API endpoint, so an agent can identify 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?

The description tells the agent to use `params` for documented filters, which is mildly actionable, but never says when to choose this tool over list_bookings, get_guest, or the other list siblings. Usage is only implied by the resource name.

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 adds the response shape including pagination keys (items, count, limit, offset, next_page_url), which is genuinely useful context, but says nothing about default page size behavior, auth, or rate limits beyond what the schema/annotations 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?

Three tightly packed sentences: identity, domain definition, endpoint, and return shape, with the most important naming/definition front-loaded. 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?

With no output schema, the description usefully enumerates the return envelope keys, and the schema carries all parameter semantics. It stops short of describing the item shape or how to filter the collection, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, and the free-form params passthrough. The description adds nothing about parameter behavior, making the 3 baseline correct.

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 channel listings') and immediately defines the domain term as a property's presence on a listing site like Airbnb/Vrbo, which disambiguates it from siblings such as list_properties and list_listing_sites. The API endpoint reference (GET /v2/listings) further pins the resource.

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?

Listing behavior is implied by the name and the endpoint, but there is no explicit when-to-use vs. get_listing (single item) or list_properties/list_listing_sites, and no guidance on filtering the collection. Usage is inferable, not 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?

The readOnlyHint annotation already declares this a safe read, so the description carries less burden. It adds the underlying endpoint (GET /v2/listingsites), which helps an agent map to the raw request tool, but says nothing about result shape or whether the list is paginated nor how many channels typically exist.

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, purpose front-loaded, followed by the API mapping. No filler, no redundancy with the title or 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?

For a simple read-only list endpoint with no output schema, full parameter documentation and a readOnlyHint annotation, the description covers what is needed to invoke it correctly. The only mild gap is return-volume/pagination expectations, which the schema partly addresses.

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 all three parameters (limit, offset, params) are documented there, including paging semantics. The description adds no parameter detail beyond the schema, 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 and resource ('List the listing sites') and clarifies the term with concrete examples ('channels, e.g. Airbnb, Vrbo'), which effectively separates it from the adjacent list_listings tool. It stops short of naming that sibling explicitly, so it is clear but not maximally disambiguating.

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?

There is no guidance on when to use this tool versus alternatives such as list_listings or ownerrez_request, no prerequisites, and no exclusions. Usage is only implied by the word 'List'.

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 the safe-read profile, so the description is not the load-bearing source of safety info. It adds the raw endpoint and the params-merging behavior, but says nothing about pagination semantics or how threading affects results.

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 sentences, purpose front-loaded, no padding. The endpoint reference is mildly redundant given the tool name but is short and harmless.

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 could have said what a message record contains or how threads group messages, and it does not. Params and annotations are otherwise adequate for a list tool, so this is minimum-viable rather than deficient.

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/offset/params are already fully documented, and baseline 3 applies. The description adds a concrete filter example (booking_id) that the schema's generic "additional documented query-string filters" text lacks, but this is a marginal gain.

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 messages from guest-communication threads") and pins it to the OwnerRez endpoint GET /v2/messages. It does not explicitly distinguish itself from near-siblings like list_inquiries, which could plausibly return overlapping guest communication.

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 or when-not-to-use guidance; nothing tells the agent how this differs from list_inquiries or when a params filter is required versus optional. The only operational hint is "Use `params` for documented filters," which is a parameter mechanic rather than usage context.

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 description meets the lower bar. It still adds value by disclosing the paginated return envelope ({ items, count, limit, offset, next_page_url }), which matters because no output schema exists, though it says nothing about auth, rate limits, or default page size.

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 fragments, zero filler, with the core purpose front-loaded. Nothing can be trimmed without losing 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 endpoint with fully documented parameters, the description plus the returned envelope is nearly enough. It stops short of mentioning available filter keys (delegated to the opaque params object) or the meaning of an 'owner' in this domain.

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%: limit, offset, and the free-form params bag are each documented in the schema itself. The description adds nothing to parameter meaning beyond the returned envelope fields, 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+resource ('List property owners') and names the underlying endpoint, which unambiguously identifies the entity. It is not confused with list_properties or list_guests, but it never explicitly contrasts itself with them, so it falls short of the sibling-differentiating 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?

There is no stated when-to-use or when-not-to-use, and no routing to alternatives. The generic ownerrez_request sibling could plausibly be used for the same call, and the description gives no cue for choosing one over the other.

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, but the description adds nothing behavioral beyond that: no pagination semantics (limit/offset tradeoffs), no ordering of results, and no note that filters are passed straight through to the upstream API. The 'merged with the typed params' detail lives in the schema, not the description.

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, each earning its place: the operation, the upstream endpoint, and the filter mechanism. Nothing is padded or repeated.

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 low-complexity list tool with no required parameters and a fully documented schema, the definition is nearly sufficient. The only omission is any hint about the returned record shape or result ordering, which is forgivable given there is no output 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 coverage is 100% and both pagination params are fully described in the schema, so baseline is 3. The description goes a step further by naming concrete filter keys (booking_id, since_utc) for the otherwise opaque free-form `params` object, which is real added value.

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 payments') and even names the underlying REST endpoint GET /v2/payments, which pins down the operation precisely. It does not explicitly distinguish itself from the sibling get_payment (single-item fetch), though the list/get naming convention makes the split reasonably evident.

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 how to pass filters ('Use `params` for documented filters'), which implies the retrieval use case, but gives no explicit when-to-use guidance, no condition for choosing this over get_payment, and no exclusions or 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?

readOnlyHint=true already establishes the safe-read profile, and the description adds real value on top of it by disclosing the pageable response envelope { items, count, limit, offset, next_page_url }. That tells the agent to expect pagination, which the annotation does not.

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: the verb+resource first, the endpoint second, the return shape third. Nothing is wasted and the most important information is front-loaded.

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 10 params all schema-documented and no output schema, the description sensibly compensates by naming the return envelope. It omits anything about when filters combine or how next_page_url should be followed, a minor gap for an otherwise complete definition.

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 one of the 10 parameters (limit, offset, active, include_tags, params, etc.) is already documented in the schema. The description adds only the paging envelope framing and no additional semantics for individual filters, 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+resource ('List rental properties') and even names the underlying API call (GET /v2/properties). It does not, however, differentiate itself from close siblings like get_property or list_listings, leaving the agent to infer the list-vs-get distinction from the names 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?

There is no explicit when-to-use guidance and no mention of alternatives such as get_property or list_listings. Usage is only implied by the phrase 'List rental properties', so an agent gets no help choosing among the several list_* and get_* siblings.

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 goes further by disclosing the exact response envelope ({ items, count, limit, offset, next_page_url }) and the fact that `params` is merged verbatim with the typed parameters. It does not mention rate limits or auth requirements, which keeps it out of the 5 range.

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: purpose, endpoint, return shape, then param guidance. The scoping and return information is front-loaded and every clause carries distinct information with 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?

With no output schema, the description compensates by spelling out the response envelope and pagination fields, and the passthrough guidance covers the one non-obvious parameter. An agent has everything needed to page through quotes 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 the baseline is 3, and the description earns an extra point by naming concrete filter keys (property_id, guest_id) that appear nowhere in the schema, clarifying what the open-ended `params` object is actually for. It does not explain merge precedence conflicts between `params` and typed params.

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 quotes") and pins it to the underlying API endpoint GET /v2/quotes, so the agent knows this enumerates the quotes collection rather than fetching a single one like get_quote. It stops short of explicitly naming the singular sibling to differentiate scope, so it lands just under the top mark.

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 how to reach documented filters ("Use the `params` passthrough for documented filters (e.g. property_id, guest_id)"), which is real usage guidance. However, it never says when to prefer this tool over get_quote, list_bookings, or ownerrez_request, so the alternative-selection question 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 provide only readOnlyHint, and the description adds real context: it is an escape hatch, only GET is permitted, the path must include the query string, and it returns parsed JSON. It does not mention auth requirements, pagination, or rate limits, but the safety and method constraints are 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 escape-hatch framing and constraint, then the calling convention, then the return type. 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 a single-parameter raw-read tool with no output schema, the description covers the calling convention, method constraint, and return shape (parsed JSON). Auth handling and pagination behavior of arbitrary endpoints are unaddressed, which is a minor gap given the tool's generic nature.

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 already shows a path example, but the description adds value by stressing the FULL path after the host, the leading slash, and that the query string must be embedded in the path, with two concrete examples including a resource-by-id path.

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 (GET) and resource (any OwnerRez API path), and explicitly positions itself relative to the other tools as the 'escape hatch' for paths 'not wrapped by a dedicated tool'. An agent can distinguish it from get_booking/list_properties 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?

Clearly frames when to use it: only for API paths that dedicated tools don't cover, implying dedicated tools should be preferred when they exist. It does not name specific siblings as alternatives, but the routing condition is stated plainly.

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; the description adds real behavioral context: it is a mutation, it uses PATCH /v2/bookings/{id}, and critically that only included fields change (partial-update semantics). It does not cover auth requirements, rate limits, or reversibility, but goes well beyond the annotation.

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?

Compact and front-loaded with the mutation warning and endpoint; the passthrough guidance follows. Dense but every clause earns its place, with only mild compression into a single long line.

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 mutation tool with no output schema and 100% schema coverage, the description covers the essential behavioral facts (endpoint, partial-update semantics, flexible field passthrough). It omits auth/error handling, but nothing needed to invoke the tool 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 already 100%, so the baseline is 3, but the description adds meaning by explaining that `fields` is merged with the typed fields and can carry any documented OwnerRez field, and by enumerating field categories (dates, guest counts, notes, status).

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 ('updates an existing booking') and flags the mutation nature immediately with 'MUTATES OwnerRez data'. This clearly distinguishes it from siblings like create_booking and get_booking.

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 useful mechanics — PATCH semantics and the `fields` passthrough for any documented field — but offers no guidance on when to use this versus the generic `ownerrez_request` sibling or update_guest. Usage is implied 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 only supply destructiveHint=true; the description adds genuine behavioral context beyond that by disclosing PATCH partial-update semantics ('only included fields change'), which tells the agent omitted fields are preserved. It stops short of stating permission requirements or whether changes are reversible, 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 tightly packed segments with the mutation warning front-loaded, then the endpoint, then the passthrough rule. Every clause earns its place and there is 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 a mutation tool with no output schema and minimal annotations, the description covers the key gaps: mutation intent, endpoint, and partial-update semantics, plus handling of the nested `fields` object. It omits auth/permission expectations and error behavior, which is the only meaningful shortfall.

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 does not: it names the array fields (email_addresses/phones/addresses) that must go through the `fields` passthrough and explains the merge behavior with the typed fields. This is real added value over the structured 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 ('updates an existing guest') and pins it to the concrete API operation (PATCH /v2/guests/{id}). This cleanly separates it from the sibling create_guest, get_guest, and list_guests tools without the agent needing to open 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?

The description implies usage (it is the update path for an existing guest) but gives no explicit when-to-use vs when-not, and no alternative routing when a create or read is actually wanted. The one real directive — route arrays through `fields` — is useful but is parameter guidance rather than tool-selection guidance.

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