Bookingmood MCP by usefulapi

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: the return payload is a list of intervals with enumerated statuses, and 'One request per product' warns that a 5-product call fans out into N requests, which matters for latency/rate awareness. It omits the time window the calendar covers, which is the one behavioral gap.

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

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

Two tightly packed sentences: the payload shape first, then the request-count/endpoint fact. No filler, and the most decision-relevant information (what comes back, and the 5-product cost) 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 no output schema and no annotations about returns, the description does responsibly describe the returned interval objects and status enum. But it leaves open what date range the calendar spans, how start/end are formatted, and whether intervals are contiguous — details an agent needs to interpret the result. Adequate, not complete.

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

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

Schema description coverage is 100%, so both parameters are already documented (UUID pattern, 1-5 count, enum default TENTATIVE). The description reinforces the 5-product limit but does not explain show_pending_as, e.g. how choosing CONFIRMED or CANCELLED reshapes the returned statuses. Baseline 3 is appropriate given the schema carries the burden.

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 (availability calendar) plus the exact result shape: per-product interval lists of {start, end, status} with five possible status values. That interval/status vocabulary clearly separates it from sibling calendar and listing tools such as list_calendar_events or get_product.

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

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

Usage is implied by the 'up to 5 products' framing and the availability-status vocabulary, so an agent can infer this is for checking whether products can be booked. However, it never says when not to use it, nor does it point to a sibling for other availability needs; no exclusions or alternatives are given.

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

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

Annotations already declare idempotentHint=false and destructiveHint=false, but the description adds the consequence ('calling it twice creates two contacts') and the important side-effect disclosure that no message is sent to the contact. The POST /contacts endpoint adds further operational 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?

Three short sentences, front-loaded with the write operation and non-idempotency warning, then the dedupe instruction, then the no-notification note. Nothing is padded.

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

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

For a 14-parameter mutation with no output schema and no annotations about the response, the description omits what comes back (e.g. the new contact ID needed for follow-up calls) and gives no guidance on which fields are meaningful despite none being required. The safety and dedupe story is complete; the parameter and return story is not.

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?

14 parameters with only 7% schema description coverage, and the description mentions no field semantics at all — it does not clarify that zero parameters are required, nor which fields (email, first_name, last_name) identify a contact. The schema does supply types and constraints, but the description makes no attempt to compensate for the coverage gap.

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

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

States a specific verb and resource ('create ONE new contact (guest/customer) in Bookingmood') and implicitly scopes it against the get/list/update_contact siblings by insisting on a single new record. The 'WRITE' prefix and endpoint signal make the operation unmistakable.

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

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

Explicitly directs the agent to search with bookingmood_list_contacts first to avoid duplicates, which is a concrete when-to-use precondition and names a sibling tool. It stops short of stating when not to use it (e.g. when a contact already exists, use bookingmood_update_contact), but the dedupe guidance is strong.

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?

Beyond the annotations (readOnly, openWorld, non-destructive), the description discloses meaningful behavioral traits: the cost (five or six read requests), the partial-failure semantics ('if that lookup fails the reply says so instead of failing'), and the underlying endpoints. This is exactly the extra context annotations cannot provide.

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 key fact ('One booking with everything attached') is front-loaded and the description is compact. The endpoint list at the end is slightly implementation-detail heavy but still supports the request-count claim and does not bloat the text unreasonably.

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

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

For an aggregate GET with no output schema, the description sufficiently enumerates the included entities (calendar events, line items, payments, invoices, guest contacts) and explains failure behavior. It does not describe the response structure (e.g., arrays vs nested objects), but that is a minor gap for an agent deciding to call it.

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 and 100% schema description coverage, the schema already defines booking_id as a UUID. The description adds no additional parameter-level meaning, which is correct for a baseline-3 case where the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('One booking with everything attached') and enumerates the attached entities, making clear this is an aggregate read rather than any of the many list_* siblings. It is distinguishable from list_bookings and the individual resource list tools 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 aggregate framing and the note that it costs 'Five or six read requests' imply when to use it (when you need the full booking with all attachments in one call). However, it never explicitly names an alternative or states when not to use it, so it falls short of a full when/when-not contrast.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no mention of what happens on an unknown id, whether the lookup is scoped to the authenticated organization, or what fields come back. The raw endpoint string is the only extra content and it conveys little to an agent.

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 fragments, front-loaded with the resource and scope. The GET endpoint echo is of marginal value to an agent but costs little space.

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

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

For a one-parameter read with full annotation coverage this is minimally sufficient, but with no output schema the description could say what a contact record contains or what a 404/empty result looks like. Adequate, not complete.

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

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

Schema coverage is 100% and the single contact_id parameter is fully documented with a UUID pattern in the schema. The description adds no new 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?

The description names a specific verb and resource (get one contact) plus the scope qualifier 'by id', which clearly separates it from bookingmood_list_contacts. It doesn't explicitly name the sibling, so it falls short of a 5.

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

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

There is no explicit guidance on when to use this instead of bookingmood_list_contacts or bookingmood_search_products; the 'by id' phrasing only implies that a known UUID is required. No prerequisites, no exclusions, no error-path notes.

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 readOnly/destructive/openWorld, so the description's added value is the disclosure that payment-provider ids and secrets are deliberately omitted — important for an agent deciding whether this tool can answer a credentials question. It stops short of noting any auth-failure or rate-limit behavior.

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

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

One dense sentence front-loads identity and scope, the field list follows, and the exclusion clause is placed before the endpoint reference. The trailing "GET /organizations." is mildly redundant for an agent but cheap and useful for 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?

With no output schema, the description carries the return-value burden and does so by enumerating name, company, plan, languages, country, VAT, domain, and contacts, plus an explicit exclusion list. That is enough to call it correctly; only error/auth behavior is left unstated.

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

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

Zero parameters, so the baseline is 4. The description adds no parameter semantics because none exist, and it sensibly spends its words on the response shape instead.

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 ("The Bookingmood organization this API key belongs to") and scopes it to the current credential, which no sibling tool touches. The field enumeration makes clear exactly what 'organization' covers, so it can't be confused with bookingmood_get_booking, bookingmood_get_contact, or bookingmood_get_product.

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

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

Implied context is strong: use this to retrieve account/tenant details tied to the API key, which is the only org-level tool among booking/contact/product siblings. No explicit when-not or prerequisites are given, but there is no competing alternative to route away from.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context: the response embeds capacities (guest-group min/max limits), and it shows the exact PostgREST query shape (select=*,capacities(*)), which tells the agent what data comes back without an output schema.

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

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

Two short sentences, front-loaded with the resource and scope, then the concrete query. 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-record read with annotations covering safety and 100% schema coverage, the definition is nearly sufficient, and it usefully discloses the embedded capacities relation in lieu of an output schema. Minor gap: no mention of not-found/error behavior.

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

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

Schema coverage is 100% and the single product_id parameter is fully documented as a UUID with a regex pattern. The description adds only that the id is interpolated into the query, so the baseline of 3 applies — 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 and resource ('One product by id') plus an important scope detail: capacities are embedded. An agent can distinguish this single-record fetch from bookingmood_list_products or bookingmood_search_products, though those siblings are not named.

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 it when you already have a product UUID — but there is no explicit when-to-use/when-not or pointer to list_products/search_products for discovery. Adequate but leaves routing 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 already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds useful behavior beyond annotations: results are newest-first, confirmed_at=null means not confirmed, and the guest access secret is never returned.

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 definition is front-loaded and compact, with the core purpose and returned fields stated first. The trailing 'GET /bookings' is mostly redundant, but the rest of the sentences carry useful 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 list endpoint with no output schema, the description gives enough context about fields, sorting, filtering, null confirmation meaning, and related resources. It does not explain pagination response details, though the offset parameter description partially covers that.

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 parameters are already well documented. The description reinforces that filtering is available by creation date, confirmation state, or reference text, but it does not add syntax or semantics 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?

The description states a specific verb and resource: list bookings, newest first. It also names the key returned fields and clarifies that booking dates and guests live on calendar events, which distinguishes this list operation from related booking/contact/calendar tools.

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 clearly says to use this tool for filtering by creation date, confirmation state, or reference text, and it redirects date/guest detail to bookingmood_list_calendar_events and contacts. It stops short of explicitly naming when not to use this tool versus bookingmood_get_booking, but the list-vs-retrieve distinction is strongly implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one behavioral fact beyond that — results are ordered by start date — but says nothing about pagination behavior, defaults, or result volume, which matters for an 11-filter list endpoint.

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

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

Front-loaded with the verb and resource, then the returned fields, then filter semantics. Three dense sentences with no filler and nothing repeated from the schema.

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

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

With no output schema, the description usefully enumerates the row fields and ordering, and the filter semantics are explained for an 11-param tool with zero required params. The remaining gap is pagination behavior, which the schema's next_offset hint only partially covers.

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 82%, so the schema already documents nearly every parameter including the arrivals/departures framing. The description's added value is mainly the concrete 'today's arrivals' example and the active_on phrasing ('who is in the property on a day'), which goes slightly beyond the schema's wording but is not essential information the agent couldn't derive.

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?

Names a specific verb and resource and enumerates the three event kinds returned (bookings, blocked periods, notes), plus the fields in each row. It implicitly separates itself from bookingmood_list_bookings by covering blocked periods and notes, though it never names that sibling explicitly.

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

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

Gives concrete guidance on which filter family to pick: date-range filters for arrivals/departures versus active_on for occupancy on a given day, with a worked example (start_date_from = start_date_to = today = today's arrivals). It lacks any explicit 'when not to use this / use X instead' 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 establish this is a non-destructive, open-world read. The description adds meaningful behavior beyond that: matching is case-insensitive substring, results are ordered newest first, and it is a GET /contacts endpoint. It does not discuss pagination behavior or result size, which is the remaining gap.

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

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

Two compact sentences with zero filler: returned fields first, then filter semantics, sort order, and endpoint. Everything is front-loaded and each 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 filter-and-list tool with no output schema, the description covers returned fields, filter semantics, ordering, and the underlying route — enough to call it correctly. Only pagination behavior and whether a total count is returned are left implicit in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds that the name/email/company filters are case-insensitive 'contains' matches, resolving which of the listed fields are actually searchable versus merely returned. limit/offset are left entirely to the schema, which documents them adequately.

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?

Names a specific verb and resource (List contacts) and enumerates the fields returned (name, email, phone, company, address, language, notes), which clearly separates it from bookingmood_get_contact or create_contact. It stops short of naming those siblings explicitly, so it is clear but not maximally differentiated.

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?

Explains how search works (name, email, or company; case-insensitive; contains) which implies when to use it, but gives no explicit when-to-use versus get_contact or when a filter is preferable over listing everything. Usage is inferable rather than stated.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond annotations: deleted coupons are omitted from results, and the endpoint is identified as GET /coupons.

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 tightly front-loaded: it names the resource, lists the relevant fields, notes the deletion exclusion, and ends with the endpoint. Every element is useful and there is no wasted text.

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

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

For a simple list tool with no output schema, the description does the important work of enumerating returned fields and disclosing the deleted-coupon exclusion. Pagination is handled in the schema, so the definition is complete enough for correct invocation, though return shape details remain minimal.

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 both limit and offset are fully documented in the schema, including default values and next_offset usage. The description adds no parameter semantics beyond the schema, which is acceptable given the high coverage.

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

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

The description states a specific verb and resource ('List discount coupons') and enumerates the key returned fields, so the agent knows exactly what this tool retrieves. It is clearly distinct from the list_* siblings by resource, though there is no coupon-specific sibling to differentiate against.

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

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

Usage is implied by the list operation and by the note that deleted coupons are excluded, which is useful context. However, the description does not explicitly state when to use this tool versus alternatives or mention any prerequisites.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond that: newest-first ordering, the returned field set, and the backing GET endpoint. It does not describe pagination behavior or error handling, which keeps it from a 5.

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

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

The description is compact and front-loaded: purpose, returned fields, filtering, ordering, and endpoint in a few short clauses. 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?

With no output schema, the description partially compensates by listing the main returned fields and ordering. It does not explain pagination output such as next_offset, though the input schema hints at it, and this is otherwise adequate for a simple read-only list tool.

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 six parameters, including limit, offset, reference, booking_id, and created date bounds. The description adds only a high-level note that filtering is by booking or creation date, while the reference filter is left to the schema.

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

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

The description states a specific verb and resource (List invoices), enumerates the returned fields, and specifies filtering and ordering. An agent can distinguish this from sibling list tools by resource 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 says what can be filtered by booking or creation date, which implies usage. It does not state when to use this versus sibling tools such as list_bookings or list_payments, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context beyond annotations: the endpoint is GET /line_items, the tool returns specific fields, and it notes that the API reference does not state the unit for amount/quantity—a valuable caveat.

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

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

The description is a single dense sentence that front-loads the purpose and packs in useful field details plus the endpoint. It is appropriately sized, though the field list is somewhat compressed.

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 helpfully lists the returned fields and notes the unit ambiguity. The input schema fully covers filters and pagination, and annotations cover safety, so the definition is nearly complete; explicit pagination-response behavior is the main minor gap.

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

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

Schema description coverage is 100%, so limit, offset, event_id, booking_id, and invoice_id are already well documented. The description lists booking_id, event_id, and invoice_id as returned fields rather than clarifying their role as filters, so it adds little parameter-specific meaning beyond the schema.

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

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

The description uses a specific verb and resource: 'List invoice/booking line items.' It also names the returned fields and ends with 'GET /line_items,' making clear it is a read/list tool for line items rather than invoices, bookings, or payments.

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

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

Usage is implied by the resource and the available filters in the schema, but the description does not explicitly say when to use this tool versus siblings such as list_invoices or list_bookings, nor does it state 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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior not in the annotations: rendered HTML is omitted, results are newest-first, and the underlying endpoint (GET /messages).

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

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

A single dense sentence followed by two short clauses — front-loaded with what is returned, then the exclusion and ordering. The trailing 'GET /messages' is slightly extraneous but costs little.

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

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

With no output schema, the description carries the return-value burden and discharges it by naming every returned field (subject, body, type, status, send_at, booking_id) and noting ordering and the HTML exclusion. An agent has enough to call it and interpret results.

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 60% with limit, offset and booking_id documented in-schema. The description reinforces which attributes exist and re-lists the type/status enum values, but adds no new syntax or semantics for the paging/filter parameters beyond what the schema already says.

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 e-mails and SMS Bookingmood sent or scheduled to guests') and enumerates the returned attributes, so an agent knows exactly what it gets. It is clearly distinct from siblings like list_bookings or list_invoices.

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?

Context is implied by the field list — an agent can infer this is the way to retrieve guest communications — but the description never states when to use it versus alternatives or any prerequisites. No sibling covers messages, so the gap is minor but real.

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 cover the read-only/non-destructive safety profile, so the description earns credit for adding real behavior: default sort order ('Ordered by due date, latest first'), the null-means-unpaid semantics of completed_at, and the honest caveat that amount units are undocumented (normally smallest currency unit). Pagination behavior is left to the schema's limit/offset/next_offset descriptions.

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

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

One dense but front-loaded sentence: purpose first, then return fields, then filtering, then ordering, then endpoint. The parenthetical field inventory is long but each item carries information an agent would otherwise have to guess.

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

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

With no output schema, the description usefully enumerates the returned fields and their null semantics, and it covers sorting. Eight params are all schema-documented, so the only remaining gap is pagination and any guidance on when this list should replace a booking-level lookup.

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 every filter (booking_id, invoice_id, due_from/due_to, completed, offline) is already documented in the schema. The description restates the filter axes at a high level without adding syntax, defaults, or combination rules beyond what the schema provides; 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 payments') and enumerates the payment subtypes (deposits, balances, offline) plus the endpoint, which distinguishes it from list_invoices. It never explicitly contrasts itself with the closest sibling, bookingmood_list_invoices, so it falls short of a 5.

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

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

The sentence 'Filter to unpaid payments, a booking or a due date' implies the intended retrieval scenarios but never states when to choose this over list_invoices or get_booking. Usage is inferable from the filter list rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it lists the specific fields returned, explains that names and descriptions are localized objects, and explicitly notes that images are not returned.

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

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

The description is two sentences and front-loads the core purpose and returned fields. Every clause adds value, and there is no redundant or filler text.

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

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

With no output schema, the description appropriately explains the return shape by listing included fields, localization behavior, and the omission of images. It could be slightly more complete by mentioning pagination response structure such as next_offset, but the essential return semantics are covered.

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

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

Schema description coverage is 100%, and both limit and offset are fully documented in the schema, including defaults and the instruction to pass the previous reply's next_offset. The description does not add parameter-level meaning 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?

The description uses a specific verb and resource: 'List the rentable products' and enumerates examples like apartments, rooms, boats, and bikes. It is clearly a product-listing tool, though it does not explicitly distinguish it from sibling tools like bookingmood_search_products or bookingmood_get_product.

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

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

The description provides no guidance on when to use this tool versus alternatives such as search_products or get_product. It does not mention exclusions, prerequisites, or conditions that would route an agent to a sibling tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that the response payload contains label, type, fee, deposit and description, but says nothing about pagination behavior, ordering, or whether results are scoped to the organization — with the field enumeration that lands at an adequate 3.

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

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

One compact sentence plus an endpoint fragment, with the substantive definition front-loaded and no filler. Every clause carries information: the resource, its three kinds, and the five returned attributes.

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 two-parameter read with full schema coverage and safe annotations, the description supplies what structured data does not: the domain meaning of 'services' and their returned fields. Only minor gaps remain around ordering and whether the list is org-scoped.

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 and offset are already documented, including the useful 'pass the previous reply's next_offset' hint. The description adds no parameter meaning of its own, 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 services') and goes further by defining what a service is in this domain: extras, fees and form fields guests add to a booking. The enumerated returned fields (label, type, fee, deposit, description) make it distinguishable from list_products or list_coupons without opening the schema. It stops short of naming a sibling, so 4 rather than 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 guidance on when to call this versus the many other list_* siblings, nor on prerequisites such as whether services must be fetched before building a booking. The only usage-shaped element is the endpoint string, which is not decision 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 cover the safety profile (readOnly, non-destructive, open-world), so the description only needs to add context — and it does: the completed_at null-means-open convention and the 'earliest due first' ordering are real behavioral details an agent would otherwise have to discover. Auth requirements and any rate limits remain undisclosed.

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

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

Two tight sentences: scope and return fields first, then filtering and ordering, with the HTTP path trailing. No filler and nothing 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?

With no output schema, the description compensates by naming the returned fields (label, due_at, completed_at, schedule, calendar_event_id) and the sort order. Pagination is left to the schema's next_offset note, which is adequate; only auth/permission context 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 every parameter is already documented with format and bounds. The description only restates the filtering intent ('open tasks or a due-date window') and adds no syntax or edge-case 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 and resource — 'List housekeeping/operations tasks attached to calendar events' — and enumerates the fields returned, so the scope is unambiguous. It does not explicitly differentiate itself from the nearest sibling, bookingmood_list_calendar_events, 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?

'Filter to open tasks or a due-date window' implies the two useful calling patterns (completed flag, due_from/due_to range), but there is no explicit when-to-use/when-not or named alternative. Usage is inferable rather than stated.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so 'Read-only (a search; nothing is booked)' largely restates structured data. The description does add real value by disclosing the response contents (per-product matching, availability, price range) and the prerequisite that occupancy keys come from bookingmood_get_product — but says nothing about rate limits, pagination, or performance/cost of a search.

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

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

Front-loaded with the returned information, then the read-only reassurance, then the occupancy note — each clause carries real meaning. The trailing 'POST /search' is a low-value implementation detail that slightly dilutes an otherwise tight description.

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

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

There is no output schema, so the description's summary of the per-product result (match status, availability, price range) is necessary and present. Combined with the occupancy sourcing hint, an agent has enough to call it correctly; only the relationship to check_availability is left unstated.

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

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

Schema coverage is 100%, so the schema already carries start/end/occupancy/option_ids semantics and the baseline would be 3. The description adds a genuinely useful cross-reference: occupancy keys must come from bookingmood_get_product capacities, which tells the agent how to construct the nested map rather than guess UUIDs.

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 specific verb+resource — searching bookable products for a stay — and even describes the per-product result shape (match on dates/guests/options, availability, price range {min, max}). It does not explicitly name the near-siblings bookingmood_check_availability or bookingmood_list_products, so the boundary must be inferred.

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: it's a search for 'a stay' that is read-only, and the occupancy pointer to bookingmood_get_product capacities hints at a required pre-step. But there is no explicit 'use this when X, use check_availability when Y', even though a sibling with an almost identical name exists.

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?

Goes well beyond the annotations by disclosing downstream consequences: calendar availability display changes and Bookingmood automations fire (guest e-mails, tasks, payment reminders). The annotations only flag destructive/idempotent/openWorld; the description explains what is actually destroyed or triggered, which is the high-value 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?

Front-loads 'WRITE:' then the operation, then the risk warning, then the endpoint — a sensible order with no filler sentences.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the description supplies everything needed: the operation, valid values, side effects, caution requirement, and the underlying endpoint. Nothing material is missing.

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

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

Schema coverage is 100% and the status enum with its three values is already defined there, so the schema carries the weight. The description adds only the scoping notion of 'ONE' event, which the required event_id already implies.

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?

Names a specific verb (change status) on a specific resource (ONE calendar event) and enumerates the three valid target states. The WRITE prefix and the PATCH endpoint make it unmistakable against read siblings like bookingmood_list_calendar_events.

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

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

Gives clear guidance on when to pause for human confirmation ('confirm with the user before cancelling or confirming'), which is actionable for an agent. It does not, however, mention alternatives such as update_event_notes for non-status edits, so the agent must infer the boundary from the name 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?

Beyond the annotations, the description discloses two non-obvious traits: PATCH-style partial semantics (unpassed fields are preserved) and that no notification is sent to the contact. It does not address the destructiveHint=true implication — that overwritten values are replaced and not recoverable — nor any permission requirements.

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

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

Three tight clauses, front-loaded with the operation type and scope, with zero filler. Every statement 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 15-parameter mutation with no output schema, the description covers the core semantics (partial update, single record, no notification) but says nothing about failure behavior, whether contact_id must exist, or what the response contains. Adequate as a minimum but with clear gaps.

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 only 13% across 15 parameters; only contact_id and language are documented in the schema, leaving the other 13 fields' semantics to field names alone. The description adds only the partial-update rule and no per-parameter guidance, so it does not compensate for the coverage gap.

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 ('change fields of ONE existing contact'), scoped to a single record, which cleanly separates it from bookingmood_create_contact and the list/get siblings. The 'WRITE:' prefix and the PATCH endpoint make the operation type unmistakable.

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

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

The clause 'only the fields you pass are changed; others stay' tells the agent this is a partial update and implies it should be used for editing existing contacts rather than creating them. It lacks an explicit exclusion (e.g. don't use for creating, or a pointer to create_contact for new records), so it falls short of 5.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description earns its keep by spelling out the exact destructive semantics (entire notes text overwritten, must re-include existing text), the notification side effect (none), and the underlying PATCH endpoint. This is richer than what the annotations 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?

Front-loaded with the WRITE marker and the core action, then the critical caveat, then the endpoint detail. Every clause carries operational information; nothing is 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 2-parameter mutation with full schema coverage and destructive/idempotent annotations, the description covers the risks an agent needs: overwrite loss, read-first workflow, and lack of guest notification. No output schema is needed for a set-notes operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond by explaining that the notes parameter wholesale replaces existing text and that existing content must be re-supplied. It doesn't restate the 5000-char limit or UUID format, but those are covered in-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?

Specific verb (replace), specific resource (internal notes of ONE calendar event), and explicit cardinality. It is clearly distinguishable from siblings like bookingmood_set_event_status or bookingmood_list_calendar_events.

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 tells the agent to read the notes first with bookingmood_list_calendar_events before calling, and explains why (overwrite behavior). It also states the 'when not to worry' condition: no guest is notified.

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