ownerrez

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

Annotations only supply destructiveHint=true and a title; the description adds that this is a write ("MUTATES OwnerRez data"), the exact endpoint and method, and that it returns the created booking. It does not disclose permission requirements, idempotency, or whether a created booking can be undone, which would be valuable for a destructive mutation.

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: mutation flag first, endpoint second, semantics/fallback last. Every sentence carries load 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 destructive creation tool with a nested `fields` object and no output schema, the description covers the return value ("Returns the created booking") and explains how to handle account-specific payload gaps. It stops short of permission/auth or error behavior, which is a minor gap given the 100% schema coverage.

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 eight parameters are already documented in the schema (including `fields` being merged into the write body). The description adds the useful note that charge/quote shape is account-specific, but otherwise adds little 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?

States a specific verb and resource ("creates a new booking (reservation)"), plus the underlying API call POST /v2/bookings. The "booking ties a guest to a property for a date range" clause distinguishes it from siblings like create_guest and create_quote without requiring schema inspection.

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: this is the creation counterpart to update_booking/get_booking and the alternative to create_quote. However, it never states explicitly when to choose this over create_quote (quote-then-book flow) or when a booking should be updated instead. The `fields` guidance is parameter advice, not tool-selection 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 only supply destructiveHint=true; the description adds real context beyond that: it is a mutation, it hits POST /v2/guests as JSON, complex array fields must be routed through `fields`, and it returns the created guest. It does not cover auth/permission requirements or side effects like duplicate handling.

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 short, front-loaded sentences with the MUTATES warning first, then endpoint, then the key parameter-handling caveat, then return value. Slightly dense but every sentence contributes; nothing is padding.

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

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

With no output schema, noting 'Returns the created guest' is valuable, and the array-via-fields caveat closes the biggest gap for a nested-object schema. Missing only auth/permission prerequisites and duplicate-guest behavior for a no-required-parameter mutation.

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 typed fields are already documented (baseline 3), but the description adds meaning the schema's generic `fields` blurb does not: emails/phones/addresses are arrays of objects and must go through the passthrough with a concrete example shape.

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 even names the underlying API endpoint POST /v2/guests. This clearly distinguishes it from siblings like update_guest, get_guest, and list_guests.

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 a concrete usage hint — pass array-shaped values like email_addresses through the `fields` passthrough — but never states when to choose this tool over update_guest or what prerequisites (auth, permissions) apply. Usage is implied rather than explicit.

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

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

The destructiveHint annotation is already present, and the description reinforces it with 'MUTATES OwnerRez data' rather than contradicting it. It adds genuinely non-structured context: the write endpoint, that the thread/booking linkage is account-specific, and that the created message is returned. It does not cover auth requirements or reversal/undo behavior, which keeps 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 the mutation warning front-loaded, followed by endpoint, linkage caveat, and return value. Slight redundancy in restating the mutation that destructiveHint already signals, but 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 3-parameter write with no output schema, the description covers the mutation, the endpoint, the linkage subtlety, and the return value. It omits any mention of permissions/scope needed to post to a thread, which is the main 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?

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining the otherwise opaque `fields` bag — it tells the agent to route thread_id/booking_id-style linkage through it. That is real added meaning beyond the generic schema text for `fields`.

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

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

States a specific verb and resource ('posts a message into a guest-communication thread') and even names the backing API operation POST /v2/messages. An agent can distinguish this from create_booking, create_guest, and list_messages 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 description explains HOW to supply account-specific linkage (via `fields` with thread_id/booking_id), which is useful operational guidance, but never states WHEN to use this tool versus alternatives like ownerrez_request or list_messages. Usage is implied by the thread/booking framing 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?

With only destructiveHint=true provided, the description adds real value: it flags 'MUTATES OwnerRez data', names the HTTP method/path, warns that the quote/charge shape is account-specific, and notes that the call returns the created quote. It stops short of covering auth/permission requirements or side effects like whether an existing quote is affected.

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 and purpose, then the endpoint, then the account-specific caveat and return value. No filler and every sentence carries information an agent needs.

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-param mutation tool with no output schema and a nested `fields` object, the description covers purpose, mutation, endpoint, variability caveat, and return value. What remains uncovered – permissions/auth requirements and any constraint on valid date ranges – is minor given the rich schema descriptions.

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 beyond it by explaining the `fields` escape hatch ('extra documented fields to send ... merged with the typed fields above') and why it exists (account-specific shape). It adds little for the date/guest params, which the schema already documents.

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

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

States a specific verb and resource ('creates a quote for a property + date range') and clarifies exactly what a quote is ('the pre-booking pricing document'), which cleanly distinguishes it from the sibling create_booking. The endpoint reference (POST /v2/quotes) further pins down the operation.

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

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

The phrase 'pre-booking pricing document' implies the usage context (quote before booking), but the description never explicitly says when to use this vs. create_booking or get_quote, nor does it state prerequisites or exclusions. Usage must be 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?

readOnlyHint=true already declares this is a safe read, so the description is not carrying the safety burden. It adds the upstream endpoint and the fact that embedded collections are opt-in, but says nothing about failure behavior (e.g. missing id) or response shape.

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: identity first, upstream mapping second, optional-parameter pointer last. No filler, and the core purpose 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?

For a single-record read with a fully documented 4-parameter schema and no output schema, the description covers purpose, endpoint, and the opt-in includes adequately. Minor gap: no note on what happens when the id does not resolve.

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 every parameter, including the three include_* booleans, is already documented in the schema. The description's mention of 'charges/guest/tags' restates those parameters without adding format or default semantics, so baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a single booking), scoped by id, which cleanly separates it from list_bookings and get_guest/get_payment siblings. The API path mapping (GET /v2/bookings/{id}) reinforces exactly which remote call this wraps.

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 third sentence tells the agent the optional includes exist ('Opt into embedded charges/guest/tags'), which is useful context, but there is no explicit when-to-use guidance or routing versus alternatives such as list_bookings or ownerrez_request. 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 only added context is the underlying OwnerRez endpoint (GET /v2/guests/{id}). It adds nothing about behavior on a missing id, permissions, or rate limits, which keeps it at the baseline for an annotated tool.

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

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

Two compact sentences, the scoping information front-loaded, with zero filler. Nothing to trim.

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 one-id read with annotations covering safety, this is nearly adequate. With no output schema present, however, the description gives no hint of what a guest object contains or how a missing id behaves, leaving a small 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?

There is a single parameter with 100% schema description coverage ('The guest id.'), so the schema already carries the semantics. The description restates the id-based lookup but adds no format, range, or sourcing detail beyond what is already documented.

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

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

States a specific verb and resource ('Fetch a single guest (contact) by id') and the 'single' qualifier implicitly distinguishes it from the sibling list_guests. It never names an alternative explicitly, so it falls just 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?

'by id' implies the usage context (you must already know the guest id), which rules out lookup-by-name or bulk retrieval. However there is no explicit when-to-use statement, no mention of list_guests as the alternative when the id is unknown, and no 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?

The readOnlyHint annotation already tells the agent this is a safe read, so the description's added load is lighter. It adds the underlying REST endpoint (GET /v2/listings/{id}), which is mildly useful context, but says nothing about auth needs, 404 behavior for a missing id, or response shape.

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 action and scope, with the endpoint as a compact second clause. 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-resource read with readOnlyHint already declared and no output schema to explain, the description covers what an agent needs to invoke it correctly. It stops just short of noting failure modes or the sibling routing, which would make it fully complete.

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

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

There is one parameter and schema description coverage is 100%, so the schema already documents 'The listing id.' The description only restates that the lookup is by id, adding no format or origin detail beyond the schema 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), a specific resource (a single channel listing), and the selection key (by id). This cleanly separates it from list_listings and the other get_* siblings without the agent needing to open 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 only implied: the id-based lookup dictates when you'd reach for it. It never names the alternative (list_listings) or states a when-not condition, so the agent must infer routing from the phrasing alone.

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 conveys the safe-read profile, and the description adds two meaningful traits beyond the annotation: that the call validates credentials and that it maps to GET /v2/users/me. It still says nothing about rate limiting or the shape of the returned user object, so it is helpful but not fully transparent.

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 parenthetical-separated clauses, zero waste, with the core purpose front-loaded before the API reference. Nothing repeats the title verbatim or pads the sentence.

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

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

For a zero-parameter, read-only tool with annotations covering safety and no output schema, the description gives enough to invoke it correctly and understand its side purpose. Only the returned user fields are undocumented, a minor gap given no output schema exists.

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, which is the baseline-4 case; there is no parameter semantics to explain or omit. The description's mention of the underlying endpoint is consistent with the empty 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 and resource ('Return the authenticated OwnerRez user') and adds a distinguishing trait, credential verification, that separates it from data-fetching siblings like get_guest or get_booking. It does not explicitly name an alternative for contrast, so it falls just 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 parenthetical '(verifies your credentials)' implies a usage context (auth/connectivity check), which is useful implied guidance. However, there is no explicit when-to-use statement, no exclusion, and no named alternative among the many sibling get_*/list_* tools.

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 only the underlying API mapping (GET /v2/payments/{id}); it says nothing about 404/not-found behavior, auth requirements, or what the response contains, so it adds modest value beyond 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 short sentences, zero filler, with the core action front-loaded before the API reference. 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 single-resource read with annotations covering safety and a fully documented one-param schema, this is nearly sufficient. Since no output schema exists, a brief note on what a payment record returns or the not-found case would have closed the 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?

Schema coverage is 100% for the single id parameter ('The payment id.'), so the schema already does the work. The description's 'by id' adds no format, type, or range detail beyond it, making 3 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'), resource ('payment'), and scope ('a single payment by id'), which cleanly separates it from list_payments among the 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?

There is no explicit when-to-use or when-not guidance and no routing to alternatives such as list_payments when the id is unknown. Usage is only inferable from the required id parameter.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful context beyond that: it names a returned field (time_zone) and maps the tool to the concrete upstream call GET /v2/properties/{id}, which helps the agent reason about auth/scope and 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?

A single tight sentence plus the endpoint reference, with no redundant or filler content. Everything is front-loaded and earns its place.

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

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

For a simple single-record read with no output schema, the description covers purpose, the REST mapping, and one notable returned field, which is enough for correct invocation. Minor gap is the absence of a not-found/error or missing-record behavior note.

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 there is only one parameter ('id', documented in the schema), so the baseline is 3. The description's 'by id' merely restates the schema rather than adding format or constraint 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?

States a specific verb+resource ('Fetch a single property by id') and explicitly scopes it to one record, which distinguishes it from the sibling list_properties. The parenthetical notes a payload detail (time_zone) that further pins down what this returns.

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 phrase 'single property by id' implicitly signals this is for one-record retrieval as opposed to list_properties, but it never names the alternative or states when to prefer one over the other. Adequate implied usage, no explicit 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 without the description's help. The description adds the underlying REST endpoint (GET /v2/quotes/{id}), which aids traceability but says nothing about failure behavior for a missing id or the auth context. With annotations carrying the read-only guarantee, this is adequate but thin.

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 action and scope before the API mapping detail. No filler, though the endpoint reference is marginally redundant for an agent that already has the tool signature.

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-only fetch with full schema coverage and readOnlyHint annotations, the description supplies enough to call the tool correctly. It lacks only error/not-found behavior, which is not essential for 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% and the single parameter (id) is fully documented in the schema as "The quote id." The description only restates "by id" without adding format, range, or lookup semantics, so the baseline 3 for schema-driven parameters 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?

"Fetch a single quote by id" states a specific verb (fetch) and resource (quote) with a scope qualifier (single, by id) that implicitly distinguishes it from list_quotes. It never names the sibling alternatives, so differentiation is left partly to inference, but the purpose itself is unambiguous.

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

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

There is no explicit when-to-use guidance and no mention of the natural alternatives (list_quotes for collections, create_quote for creation). An agent can infer it is the single-record read, but nothing in the text routes it away from the sibling list_quotes.

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 signals a safe read operation. The description adds useful context beyond the annotation: the exact HTTP endpoint (GET /v2/bookings) and the shape of the paginated response. It stops short of mentioning rate limits or auth requirements, but provides solid behavioral detail.

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

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

The description is short, front-loaded with the core purpose, and then efficiently covers API endpoint, filters, and return shape. Every sentence earns its place with no redundancy.

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

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

For a list tool with 13 optional parameters and no output schema, the description provides the endpoint and return shape, which is enough to invoke correctly. It omits details about the generic `params` object and pagination semantics, but the schema covers parameter-level specifics.

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 13 parameters in detail. The description summarizes filter categories (property, date range, changed-since, status) and optional includes, which adds some framing, but does not explain syntax, constraints, or the generic `params` object beyond what the schema provides.

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

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

States a specific verb ('List') and resource ('bookings (reservations)'), and names the API operation. The verb clearly distinguishes it from sibling tools like get_booking, create_booking, and update_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?

The description explains what can be filtered and embedded, which implies typical usage. However, it does not state when to use this tool versus alternatives such as get_booking or list_payments, nor does it provide any 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds a minor piece of context by mapping the tool to the OwnerRez GET /v2/fielddefinitions endpoint. It does not disclose pagination defaults, auth needs, or result ordering beyond what the schema's limit/offset descriptions already state.

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 resource and followed by the clarifying definition and endpoint. No filler or repetition of 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?

For a simple read-only list endpoint with fully documented parameters, the definition is nearly complete; it even hints at what the records describe. The remaining gap is the absence of an output schema combined with no description of the returned record shape or pagination behavior, though this is minor here.

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

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

Schema description coverage is 100% for all three parameters, so the schema carries the parameter burden (limit, offset, and the verbatim params escape hatch). The description adds no additional parameter semantics, which is the baseline 3 case.

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) plus a disambiguated resource (custom-field definitions), and the parenthetical clarifies that a 'field definition' is the schema for custom fields on properties/bookings/guests — a term that would otherwise be ambiguous. No sibling tool overlaps this resource, so an agent can select it without opening another 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 says what is returned but gives no explicit when-to-use guidance, prerequisites, or alternatives (e.g. 'call this before creating/updating bookings that set custom fields'). Usage is only implied from 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?

With only readOnlyHint=true in annotations, the description adds real value: it discloses the server-side requirement (a failure mode the agent would otherwise hit) and the paginated return shape. It does not cover auth/permission needs or item-shape details, but the requirement disclosure is the important behavioral fact.

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 first, then the hard constraint, then the response envelope. No filler, and the most operationally important fact (the required filter) 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?

For a 9-parameter tool with a nested passthrough object and no output schema, the description compensates well by stating the return envelope (items, count, limit, offset, next_page_url). It stops short of explaining the `params` escape hatch or the from/to arrival-vs-departure semantics, which the agent must infer.

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 every parameter including the q/created_since_utc requirement. The description restates that constraint but adds no syntax, defaults, or meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('List guests (contacts)') and even maps it to the underlying endpoint (GET /v2/guests), which lets an agent distinguish it from get_guest and the other list_* siblings 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?

The NOTE gives the decisive prerequisite for calling this endpoint at all: either `q` or `created_since_utc` must be supplied. That is genuinely useful routing/precondition guidance, though it does not explicitly say when to prefer this over get_guest or sibling list tools.

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 backing REST endpoint (GET /v2/inquiries), which hints at pagination semantics, but says nothing about return shape, paging behavior, or authentication beyond what the schema and 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 short declarative sentences, front-loaded with the identity of the resource. The endpoint reference is arguably extraneous for an agent, but it is compact and does not bury the key information.

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

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

For a read-only listing tool whose annotations supply the safety profile and whose schema fully documents paging parameters, the description covers enough to call it correctly. It would be stronger with a note on pagination defaults or the inquiry-to-booking distinction, but no critical gap remains.

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, and params are fully documented in the schema itself. The description only echoes that `params` carries filters, adding no syntax, format, or merge-behavior detail beyond the schema 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 and resource ('List guest inquiries') and adds a useful domain gloss ('pre-booking leads') that clarifies what an inquiry is. It does not, however, distinguish itself explicitly from list_bookings or list_guests, leaving the agent to infer the boundary.

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 only guidance is 'Use `params` for documented filters', which is an invocation hint, not a when-to-use statement. There is no indication of when an inquiry list is preferable to list_bookings or any sibling, nor any prerequisite or exclusion.

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: the underlying endpoint (GET /v2/listings) and the pagination envelope returned, which matters since no output schema exists.

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

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

Three tight sentences: purpose/definition first, endpoint second, return shape last. Zero filler and appropriately 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?

For a simple read-only list tool with full schema coverage and no output schema, the description covers purpose, endpoint, and return envelope. It lacks only explicit sibling routing, which is a minor gap given how clear the name and definition are.

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 well documented in the schema. The description adds nothing about parameter syntax or filtering semantics, so baseline 3 applies.

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

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

States a specific verb (List) and resource (channel listings), and defines the domain term as 'a property's presence on a listing site such as Airbnb/Vrbo', which helps distinguish it from conceptual siblings like get_listing. However, it does not explicitly contrast itself with get_listing or list_listing_sites, leaving the agent to infer the single-vs-many distinction.

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 a read/list operation but gives no explicit when-to-use guidance and names no alternatives. An agent looking to fetch one listing versus many, or listings versus listing sites, gets no routing help from the text.

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 upstream endpoint (GET /v2/listingsites) and the fact that the result set is OwnerRez's known channel list, but says nothing about pagination behavior, result size, or whether the list is static reference data.

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

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

Two short sentences with zero filler; the purpose and its clarifying examples come first, and the endpoint reference is secondary. 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 read-only, zero-required-parameter list tool with full schema coverage and no output schema, the description is nearly sufficient. It could mention that the response is a collection of channel records and how paging interacts with limit/offset, but the schema already carries those details.

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

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

Schema description coverage is 100% and all three parameters (limit, offset, params) are documented in the schema, so the baseline of 3 applies. The description contributes no additional parameter meaning, format, or default guidance beyond what the schema already provides.

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

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

States a specific verb (List) and resource (listing sites), and immediately disambiguates the term with concrete examples ('channels, e.g. Airbnb, Vrbo'), which cleanly separates it from the nearby sibling list_listings (properties). An agent can pick the right tool 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 only implied: this is a reference-data lookup for channel identifiers. There is no explicit statement of when to use it versus list_listings, nor any prerequisite or exclusion, so the agent must infer intent from the parenthetical examples.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds the upstream endpoint and the filter-passing mechanism, which is moderate value. It still says nothing about result ordering, pagination behavior, or thread grouping that an agent might care about.

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 with no filler. The API-route sentence is slightly redundant with the tool name but can aid agents mapping to the raw endpoint.

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 and fully documented typed parameters, the description covers purpose, endpoint, and filtering adequately. The open-ended `params` object remains loosely specified, but the schema carries most of the load.

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 limit/offset are fully documented in the schema, so the baseline is 3. The description adds only a single example filter (booking_id) for the open-ended `params` object, which is marginal extra meaning beyond what the schema states.

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?

"List messages from guest-communication threads" gives a specific verb and resource, and naming the API route (GET /v2/messages) reinforces the read scope. It is distinct from create_message, but it doesn't explicitly differentiate itself from closely related read siblings like list_inquiries that also surface 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?

The description implies a standard listing use case and offers a filtering hint ("Use `params` for documented filters (e.g. booking_id)"). However, it never states when to choose this tool over list_inquiries or other siblings, nor any 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 this as a safe read, so the description only needs to add context beyond that. It does add the return envelope shape and the upstream endpoint, but says nothing about pagination behavior, rate limits, or result ordering.

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

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

Three short sentences, zero filler, and the core purpose is front-loaded before the endpoint and return details. 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?

For a read-only paginated list with full schema coverage and a readOnly annotation, the description covers purpose, transport, and return keys (items, count, limit, offset, next_page_url), which compensates for the absent output schema. Only the lack of use-case/routing guidance keeps it from being fully complete.

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

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

Schema description coverage is 100%, so limit, offset, and the verbatim params bag are already fully documented in schema. The description restates limit/offset only implicitly via the return shape and adds no syntax or filter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('List property owners') and reinforces it with the concrete upstream endpoint GET /v2/owners. It does not differentiate itself from sibling list_* tools (list_properties, list_guests, etc.) or explain what an 'owner' means versus a 'guest' or 'property', 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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as get_property or list_properties. An agent gets no help deciding between this and the other list_* 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?

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lighter burden. It adds the concrete HTTP endpoint and notes that params are merged with typed params, but says nothing about pagination behavior, result caps, or auth requirements beyond what the annotation and schema imply.

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

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

Three short sentences, front-loaded with the action and the endpoint. No filler, though the endpoint line is more operational detail than selection 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 description should ideally hint at the response shape and pagination contract, but it does not. The `params` escape hatch is under-explained ('documented filters' with no reference to where they are documented), leaving gaps for a list tool with a nested free-form 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?

limit and offset are fully covered by the schema (100% coverage), and the description names real filter keys (booking_id, since_utc) for the open-ended `params` object, which the schema cannot enumerate. That adds genuine meaning beyond the structured fields.

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

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

States a specific verb and resource ('List payments') and pins the underlying endpoint (GET /v2/payments). It is distinguishable from get_payment, but it never explicitly contrasts the list vs. single-fetch siblings, so it stops short of full sibling differentiation.

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 says to use `params` for documented filters and gives two examples (booking_id, since_utc), which implies the filtering use case. However, there is no guidance on when to prefer this over get_payment or the list_* siblings, and no exclusions or pagination 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 safety is covered. The description adds value the structured fields do not: it discloses the endpoint and, since no output schema exists, the shape of the returned pageable envelope with next_page_url, which tells the agent results are paginated. It stops short of stating default page size behavior or 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?

Three short sentences with zero padding: purpose, endpoint, and return shape, with the core purpose front-loaded. Nothing repeats the title or is extraneous.

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, the schema fully documents inputs and the description supplies the return envelope that would otherwise be missing without an output schema. The remaining gap is operational guidance (default page size, how to retrieve all pages) and sibling disambiguation.

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 ten parameters (including the free-form 'params' bag and include_* flags) are already documented in the schema, making the baseline 3 correct. The description adds no filter syntax, format, or interaction details beyond what the schema provides.

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

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

The description states a specific verb and resource ('List rental properties') and pins it to the concrete API call GET /v2/properties. It is clearly distinguishable from get_property by the list-vs-single semantics, though it never names the sibling or 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?

There is no guidance on when to use this tool versus get_property or the other list_* siblings, nor any stated exclusions or prerequisites (e.g., auth scopes, which filters are required to avoid a huge result set). Usage is only inferable from the verb '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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful context beyond that: the pagination model (limit/offset) and the exact return envelope { items, count, limit, offset, next_page_url }, which the annotation does not 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, front-loaded with purpose then return shape and filter usage. No filler; each clause 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?

With no output schema, the description compensates by describing the return envelope and pagination fields. It's nearly complete for a list tool; the only gap is absence of explicit routing to sibling tools.

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% (baseline 3), but the description adds value beyond the schema by naming concrete filter keys (property_id, guest_id) that the schema only refers to generically as "documented query-string filters." That is meaningful guidance the schema omits.

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 even pins the underlying API endpoint (GET /v2/quotes), which is unambiguous. It doesn't explicitly contrast with get_quote/create_quote siblings, but the "List" verb distinguishes it adequately.

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 this is the read/list operation and tells the caller how to apply filters via params, but it gives no explicit when-to-use versus get_quote or how it differs from list_bookings/list_guests. 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 already declare readOnlyHint=true, and the description reinforces this with 'READ-ONLY — only GET is allowed', so it does not contradict them. It also adds useful behavioral context: the response is parsed JSON. It omits auth requirements and rate-limit/error behavior, keeping it below 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?

Front-loads the purpose ('Power-user escape hatch'), then covers the constraint and the path format with examples. Every sentence earns its place, with only minor redundancy between the description and the schema's path example.

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 freeform-path tool with no output schema, the description covers purpose, method restriction, path format, and return type (parsed JSON), which is sufficient to invoke correctly. Auth scope and error behavior are the only notable omissions, and there is no output schema to compensate for.

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 beyond the schema by stressing that the FULL path after the host must be passed including any query string, and supplies two concrete examples with different shapes. This clarifies the one freeform parameter meaningfully.

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 ('GET any OwnerRez API path') and explicitly positions itself as an escape hatch for paths 'not wrapped by a dedicated tool', which cleanly separates it from the many get_*/list_* siblings. An agent can tell immediately what this does and when it applies.

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 'not wrapped by a dedicated tool' clause gives a clear when-to-use condition and implicitly routes the agent to dedicated tools first, which is the key decision against ~25 siblings. It stops short of naming specific alternatives or stating exclusions/misuse cases, so it is strong but not fully explicit.

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

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

The destructiveHint annotation already flags mutation risk, and the description adds valuable semantics beyond it: that only included fields change (partial update) and that fields merge with typed params. It stops short of covering reversibility, permission requirements, or error behavior, but the partial-update disclosure is genuinely additive over 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?

Two compact sentences plus the API reference, front-loaded with the mutation warning. Every clause carries information (mutation, endpoint, partial-update semantics, passthrough). Slightly dense but no wasted sentences.

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

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

For a mutation tool with no output schema but full annotation and schema coverage, the description supplies the key behavioral contract (PATCH semantics, partial update, fields merge). Gaps remain around failure modes and any required permissions, but the essential call information is present.

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 on top: it clarifies the partial-update contract ('only included fields change') and that the `fields` passthrough is merged with typed fields. This explains the interplay between parameters in a way the schema alone does not.

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?

Opens with a specific verb and resource ('updates an existing booking') and even names the underlying API operation (PATCH /v2/bookings/{id}). This clearly distinguishes it from siblings like create_booking, get_booking, and update_guest without needing 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?

Provides concrete guidance on how to use the tool ('use the `fields` passthrough for any documented field'), which is useful operational context. However, it never states when to prefer this over siblings such as update_guest or ownerrez_request, so routing guidance is only implicit.

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

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

The destructiveHint annotation already flags this as a mutation, and the description reinforces it with 'MUTATES' plus a critical behavioral detail the annotations do not carry: PATCH semantics where only included fields change. It stops short of noting auth requirements, side effects on related records, or idempotency.

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 and endpoint before the parameter guidance. Every sentence carries actionable information with no repetition of 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?

For a 7-parameter mutation tool with a nested passthrough object and no output schema, the description covers the mutation risk, PATCH semantics, and the role of the `fields` catch-all. It is complete enough to invoke correctly, though it omits confirmation of what a successful response returns.

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 beyond the schema by explaining that `fields` is a passthrough for arrays and undocumented fields, and that the body is merged with the typed fields. This clarifies how `fields` interacts with the typed properties rather than merely restating them.

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 guest') and anchors it to the underlying API operation PATCH /v2/guests/{id}, which distinguishes it from the sibling create_guest and update_booking. An agent can identify the tool 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?

Explicitly directs the agent to use the `fields` passthrough for arrays (email_addresses/phones/addresses) and other documented fields, which is clear routing guidance. It lacks any when-not-to-use or prerequisite guidance (e.g., required permissions), so it falls short of a 5.

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