Checkfront MCP by usefulapi

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

Annotations provide only destructiveHint=true and a title, so the description carries most of the behavioral burden. It usefully discloses the audit/attribution behavior (note is logged under the acting staff account) and the underlying endpoint, but says nothing about permission requirements, what happens if booking_id is invalid, or whether the note is visible to customers.

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 with the core action front-loaded, followed by an endpoint reference. The trailing API path is marginally useful for traceability but is not strictly needed for selection or invocation.

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, fully-documented-schema mutation with no output schema, the description covers purpose, attribution, and endpoint. It omits only secondary details such as permission prerequisites and post-call confirmation 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 description coverage is 100%, so both parameters (booking_id format example, body 1–3000 chars) are already fully documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline 3.

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

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

States a specific verb (add) and resource (note to a booking) and clarifies the attribution model — the note is logged under the staff account the API acts on behalf of. The add-versus-list distinction from the sibling checkfront_list_booking_notes is unambiguous from the verb alone.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative. The description only implies the obvious action of adding a note, which is already conveyed by the tool name and title.

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

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

Annotations only declare destructiveHint=true, so the description earns credit for disclosing that inventory is held while the session is open, that nothing is committed until checkfront_create_booking, and that a session_id is returned for reuse. It does not explain what makes the operation destructive (e.g. 'remove' clearing a line) or any session expiry/error behavior, so it stops short of a 5.

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

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

Front-loaded with the core action, then branches into the three modes; the endpoint reference is a useful trailer. It is dense and slightly over-packed in the first sentence, but virtually every clause carries semantic weight.

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 4-parameter, nested-object, no-output-schema mutation tool, the description covers workflow position, input provenance, and the returned session_id. It omits failure modes and session lifetime/expiry, which would be needed for a 5.

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

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

Schema coverage is 100% (baseline 3), and the description adds relational meaning the schema can't express: line_id is only meaningful 'with a single slip' to REPLACE a line, and alter changes are keyed by line_id with a number setting quantity and 'remove'/'optin'/'optout' for package add-ons.

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 ('Start or modify a booking session') and enumerates the three supported operations (add SLIPs, replace a line, alter lines). It also distinguishes itself from the sibling checkfront_create_booking by stating 'NOTHING is booked until checkfront_create_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?

Explicitly states the prerequisite for input ('SLIPs from a rated checkfront_get_item / checkfront_list_items call'), the condition for omitting session_id ('Omit to start a new session'), and the lifecycle boundary relative to create_booking. An agent knows exactly when to call this versus create_booking.

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

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

Annotations only provide destructiveHint=true, so the description adds real value: it discloses the side effect ('Checkfront adds a note under the acting account') and the eligibility precondition excluding VOID/cancelled bookings. That is meaningful behavioral context beyond the annotation, though reversibility and failure behavior are not described.

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

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

Three short sentences, front-loaded with the core action and followed by side effect, constraint, and endpoint. Every sentence carries information. The raw 'POST /api/3.0/...' sentence is mild implementation detail an agent rarely needs, keeping it from a 5.

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

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

For a two-parameter mutation with a fully covered schema and no output schema, the description covers the action, the side effect, and the eligibility rules, which is close to sufficient. It stops short of naming the sibling alternative and does not clarify what a successful check-in changes beyond the 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%, so the schema already documents both parameters including the checkin/checkout enum, giving a baseline of 3. The description restates the two modes in prose but adds no format or edge-case detail 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 action on a specific resource: 'Mark a guest as arrived (check in) or departed (check out).' The parenthetical maps the verb to the domain names for both modes, so an agent understands the tool immediately. It does not name its closest sibling (update_booking_status) to differentiate the two, keeping it at 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?

Usage is implied by the description but never stated as a when-to-use rule, and no alternative is named despite checkfront_update_booking_status covering similar territory. The constraint that 'VOID and cancelled bookings cannot be checked in or out' is a genuinely useful precondition that partially compensates.

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

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

Annotations only carry destructiveHint=true, so the description must add most of the behavioral context — and it does: it discloses that the call creates a real reservation, consumes inventory, and may notify the customer, plus what the response contains (booking ids, invoice/payment URL). It stops short of idempotency, retry safety, or auth/permission requirements, which would be useful for a commit-style 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?

Front-loaded with the action, then inputs, side effects, follow-up tool, and return shape, closing with the raw API route. It is a single dense block with semicolon-separated clauses; every element earns its place, though the reference-heavy style makes it slightly harder to scan than short discrete 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 3-parameter mutation with a nested form object and no output schema, the description covers prerequisites (form fields via checkfront_get_booking_form), side effects (inventory consumption, customer notification), return values, and the modification path. Nothing needed to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains that session_id and slip are alternative entry paths, gives example/tipically-required form keys (customer_name, customer_email), and points to another tool for the authoritative required-field list.

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 ('Commit a booking') and immediately distinguishes itself from siblings by naming checkfront_add_to_booking_session (session building), checkfront_get_booking_form (field requirements), and checkfront_update_booking_status (later changes). An agent can place this tool in the booking lifecycle without opening any other 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 gives the two mutually exclusive input paths (from a session_id built via checkfront_add_to_booking_session, or directly from SLIPs) and routes the agent to checkfront_get_booking_form for required fields. It also names the follow-up tool for modifying the reservation, so when-to-use and when-to-use-something-else are both covered.

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 marks this as destructive, and the description usefully qualifies that destructiveness: it 'releases the inventory it was holding' while 'no booking is affected'. That is real added context beyond the annotation, though it omits prerequisites such as auth scopes or whether the session_id must be currently active.

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

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

Two tight sentences, with the core action and the clear/end distinction front-loaded before the supporting side-effect note. The trailing API endpoint reference is extra detail that earns only marginal value for an agent caller.

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 no output schema and light annotations, the description covers purpose, action semantics, and the key side effect (inventory release, bookings untouched). It is largely complete, missing only what the call returns or any authorization requirements.

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 parameters (session_id, action enum) are already documented in the schema, so the baseline is 3. The description only restates the enum semantics ('clear' empties, 'end' closes) without adding format, default, or edge-case detail 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 gives a specific verb+resource ('Abandon a booking session') and disambiguates the two supported actions, 'clear' vs 'end'. It implicitly separates itself from siblings like add_to_booking_session and get_booking_session by stating 'no booking is affected', but it never names an alternative tool explicitly, 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?

Usage is only implied via 'Abandon a booking session' plus the meaning of each action; there is no explicit guidance on when to clear vs end, or when abandoning is preferable to an alternative tool. Adequate but leaves the agent to infer the scenario.

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 behavioral context — the result is day-by-day availability, and it maps to the GET /item/{item_id}/cal endpoints — but it says nothing about response shape, pagination, or date-range limits, so the added context is modest.

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

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

Two front-loaded sentences: scope first, then the use case, then the underlying API paths. Tight overall, though the raw endpoint reference is mildly redundant for an agent and slightly dilutes the clarity.

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, 4-parameter, non-required-parameter tool with no output schema, the description covers scope, granularity, and intent adequately. It leaves the shape of the returned calendar undocumented, which is a minor gap rather than a functional one.

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 description's mention of item_ids (one vs several) and category mirrors what the schema already documents for start_date, end_date, item_ids, and category_id. Baseline 3 applies because the schema does the heavy lifting and the description adds no new syntax or format 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 ('day-by-day available inventory over a date range') plus scope granularity (single item, several items, or a whole category). This distinguishes it cleanly from siblings like list_items or get_item, which return entity data rather than per-day availability.

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 a concrete use case — answering 'which days next month still have space?' — which tells the agent the right scenario. It does not name an explicit alternative or exclusion (e.g., when to prefer a booking search over the calendar), so it falls just short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read. Beyond that, the description adds real value by disclosing what the payload contains (form fields, line items, totals) and mapping to the underlying GET endpoint, which is useful given there is no output schema. It omits auth/permission and rate-limit context, so it is not a 5.

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

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

One sentence enumerating the payload plus a short endpoint mapping — front-loaded with the verb and resource and free of padding. Every clause earns its place.

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

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

With no output schema, the description carries the burden of describing return content and does so reasonably well for a single-key read tool. The only meaningful gap is the absence of any routing guidance relative to the sibling list/session 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 description coverage is 100% and the single parameter is documented with a concrete example ('CFPP-290317'), so the description is not needed to explain it. The description adds no format or semantics beyond what the schema already carries, which is the expected baseline.

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

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

States a specific verb ('Fetch') and resource ('one booking') and enumerates the returned data shape (status, dates, customer, form fields, line items, totals). The 'one booking' phrasing implicitly separates it from checkfront_list_bookings, but it never names or contrasts with 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?

Usage is only implied: the agent infers this is the detail-fetch counterpart to list_bookings, and the required booking_id implies a prior lookup. There is no statement of when to prefer this over checkfront_get_booking_session or checkfront_list_bookings, and no prerequisites stated.

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

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

The readOnlyHint annotation already establishes this is a safe read; the description reinforces it and adds the useful sequencing context (prerequisite for create_booking) plus the shape of the returned data. It does not need auth/rate-limit detail for a zero-parameter read, so this is solid but not exceptional.

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, payload contents, and the chaining instruction, all front-loaded with zero filler. The API endpoint reference is a compact extra rather than padding.

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

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

No output schema exists, so the description must describe return values itself, and it does so concretely (field id, label, type, required flag). Combined with the chaining guidance, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so per the baseline the schema carries no semantic burden for the description to compensate for. The description's mention of `form` fields is context for the downstream call rather than a parameter of this tool.

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 the customer-details form for a booking') and describes exactly what the payload contains (field id, label, type, required). It is clearly distinguishable from siblings like checkfront_get_booking or checkfront_create_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?

Explicitly instructs 'Call this before checkfront_create_booking to know which `form` fields to send,' naming the sibling and the condition that selects it. Nothing about when to reach for this tool is left to inference.

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds valuable return detail (line items keyed by line_id, dates, sub_total, tax, total, amount due) plus the exact REST endpoint, though it omits session-expiry/rate-limit or emptiness behavior.

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

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

Two compact sentences, front-loaded with the purpose and the return contents; the trailing API path is a minor extra but useful for developer alignment. No padding or repetition.

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, single-parameter tool with no output schema, the description compensates by enumerating the key returned fields. What an agent needs to invoke it correctly is largely present; minor gaps are session lifecycle and error/empty-state 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 description coverage is 100% and the single parameter is already fully documented, including its provenance from checkfront_add_to_booking_session. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Read') and resource ('booking session'), then clarifies the resource as the in-progress cart, which cleanly distinguishes it from the sibling checkfront_get_booking (a confirmed booking). An agent can tell what it returns without opening the schema.

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

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

Usage is implied rather than stated: 'in-progress cart' and the note that session_id comes from checkfront_add_to_booking_session suggest the retrieve-after-add flow. However, there is no explicit when-to-use vs an alternative (e.g., when to call this instead of checkfront_get_booking) and no stated prerequisites.

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

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

Annotations already declare readOnlyHint=true, so safety is covered by structured data. The description goes beyond that by characterizing cost ("cheap") and by enumerating exactly what comes back, which tells the agent this is a low-side-effect diagnostic rather than a data-mutating call. No auth-scope or rate-limit detail, so not a 5.

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

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

Two sentences plus a trailing endpoint reference, with the resource and the field list front-loaded and the practical rationale second. No filler, no restatement of the title.

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

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

There is no output schema, so the description correctly compensates by listing the fields the call returns, and the zero-parameter schema needs no explanation. An agent has everything required to decide whether to invoke it and what to expect.

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

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

The tool takes zero parameters, so there are no parameter semantics to document — baseline 4 per the rubric. The description instead spends its words on the return payload, which is the relevant information for a no-arg call.

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 (the connected Checkfront account's company configuration) and enumerates the actual fields returned — name, URL, plan, currency, timezone, locale, date/time formats. It is cleanly distinguishable from every sibling, none of which touch account-level settings.

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 frames the use case: "A cheap way to confirm the host and credentials work." That resolves the main ambiguity an agent would have (why call this at all?) and implies it is a low-cost connectivity/auth probe. It stops short of naming alternatives or when-not-to-use conditions, so it does not reach 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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that, the description discloses the return payload — contact details plus bookings as codes with created dates — which is genuinely useful since no output schema exists. It stops short of covering auth needs, error behavior, or whether the bookings list is paginated.

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 payload description; the endpoint citation is trailing reference material rather than a distraction. No filler, though the raw GET path is somewhat redundant for an agent.

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

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

For a one-parameter read-only tool with no output schema, the description supplies the missing return-shape information an agent needs. What remains uncovered — error cases, permissions, pagination of the embedded bookings — is minor for this tool class.

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 documents both the numeric id and the 'customer code' form. The description adds nothing beyond the schema and merely restates the endpoint path, 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 ('Fetch one customer's contact details and their bookings'), which clearly separates it from list-style siblings like checkfront_list_bookings. It does not name checkfront_search_customers as the lookup alternative, so sibling differentiation is implicit rather than explicit.

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 singular 'one customer' and the required customer_id, but there is no statement of when to prefer this over checkfront_search_customers or how to obtain a valid id in the first place. A competent agent can infer the case, but it is not spelled out.

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

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

readOnlyHint=true already covers the safety profile, so the description earns credit for adding response-level behavior: a rated response exposes rate.status, rate.available, a price breakdown, and the SLIP used to book. The parent/child rating rule is a genuine gotcha not derivable from the schema. No output schema exists, so this disclosure matters.

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

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

Front-loaded with purpose, then the rated-mode detail, the parent/child caveat, and the underlying endpoint. Four compact sentences with little waste; the trailing API route is the only arguably expendable element.

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?

Ten parameters with no output schema and only a readOnlyHint annotation, so the description carries the response-shape burden and does so for the rated path. The non-rated response shape and how the many optional time/package/discount parameters compose are left to the schema, which is acceptable given 100% 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 baseline is 3, but the description adds real value by tying start_date/end_date/param together into the 'rated response' workflow and showing a concrete param shape ({"adults": 2}). This explains why those optional parameters exist, which the per-field schema text only hints at with '(rated)'.

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 one inventory item's details') and the singular 'one' implicitly separates it from checkfront_list_items. It never names a sibling, so an agent must infer the browse-vs-fetch split rather than being told it.

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 conditional guidance on how to invoke it: supply start_date/end_date plus param for a rated response, and rate the CHILD for parent/child grouped items. It never states when to prefer this over checkfront_list_items or checkfront_get_availability_calendar, so alternative selection is left to inference.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered; the description adds real behavioral context beyond that: the default date window, the meaning of author account id (0 = customer), the private flag, and the underlying API route. It omits pagination/result-limit behavior, which is the main remaining gap.

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

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

One dense sentence carries scope, default, and return shape, with the endpoint appended as a compact reference. Nothing is padded and the most decision-relevant facts come first.

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

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

With no output schema, the description compensates by enumerating returned fields (booking code, author id, date, body, private flag) and the default time window, so an agent knows what it will get. Only result volume/pagination behavior is left unspecified for what is otherwise a simple single-param 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 coverage is 100% on the single date parameter, so the baseline is 3, but the description adds the default-window semantics that the schema does not express. That extra meaning justifies a 4 rather than a flat 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 the notes left on bookings across the account') and enumerates the returned fields, which cleanly separates it from the write-side sibling checkfront_add_booking_note. 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?

Discloses the default scope ('default: the past 30 days'), which tells the agent what happens if it omits the date parameter. There is no explicit statement of when to prefer this over an alternative or how to get an unbounded window, so it stops short of a full when/when-not rule.

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

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

With only readOnlyHint available in annotations, the description carries useful extra burden: it discloses paging behavior (default 100/page), where the page count lives (request.pages), and the exact shape of a returned row. It does not discuss rate limits or ordering semantics beyond the ambiguous 'newest filters first'.

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 dense sentences with the resource and filters front-loaded and no filler. The only drag is the unclear 'newest filters first' clause, which reads ambiguously and slightly muddies the opening line.

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

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

For an 11-param, zero-required, all-optional list tool, the description covers filtering, row shape, and pagination well. The absence of an output schema means the row-field enumeration is genuinely needed context, though page/limit interaction and default ordering could be spelled out more precisely.

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 11 parameters — including the '<'/'>' date prefix syntax — are already fully documented in the schema. The description only restates which filters exist, adding no syntax or default detail beyond what structured data provides, so the baseline 3 applies.

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

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

Names a specific verb+resource ('List bookings') and enumerates the filter dimensions (status, customer, dates, item, partner) plus the fields each row returns, so the agent knows exactly what the call produces. It does not explicitly differentiate from the sibling `checkfront_get_booking`, though the singular/plural naming makes the distinction inferable.

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 filter enumeration implies when the tool is useful (broad retrieval narrowed by status/customer/date/item/partner), but the opening phrase 'newest filters first' is garbled and there is no explicit when-to-use vs. alternatives or exclusion guidance. 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, so the safety profile is covered; the description adds value by disclosing the response shape (ids, names, display order, item counts) and the backing endpoint, which is meaningful given there is no output schema. It does not mention pagination or auth requirements.

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

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

Two tightly packed sentences: the resource and returned fields come first, followed by the API endpoint. 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?

Because no output schema exists, the description usefully compensates by enumerating the fields returned; for a zero-param list tool this is nearly complete, with only minor gaps such as pagination or ordering guarantees.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

Specific verb+resource ('List the inventory categories') with concrete examples (Tours, Rentals, Accommodations) and an explicit enumeration of returned fields, which clearly separates it from the sibling checkfront_list_items.

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 zero-parameter, read-only nature of the call, but the description gives no explicit when-to-use or when-to-prefer-an-alternative guidance (e.g., versus checkfront_list_items or checkfront_get_item).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is naming the returned fields (dates, recurrence, pricing rule, items/categories). It does not disclose pagination, result size, or auth scoping. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two tight sentences, front-loaded with the definition and event taxonomy, followed by the API endpoint mapping. No filler; every clause carries 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 parameterless read-only list with no output schema, the description carries nearly the full burden and does describe the returned record shape (dates, recurrence, pricing rule, applicable items/categories). It stops short of describing pagination or response envelope details, leaving a small gap.

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

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

The tool takes zero parameters, which is the baseline-4 case. Nothing in the schema needs description coverage, so no compensating prose is required.

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 (date-based events) and then enumerates the exact event categories with their API codes (SE, SP, DC, status U). This distinguishes it from siblings like list_items, list_categories, and get_availability_calendar 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?

Usage is implied by the content description — an agent can infer this is the tool for inspecting pricing/availability events — but no explicit when-to-use or when-to-prefer-an-alternative guidance is given. The natural sibling relationship with get_availability_calendar is never addressed.

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

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

Annotations only declare readOnlyHint, so the description carries the behavioral load and does add useful context: two distinct response modes, that only enabled items are returned, and that the rated response includes a SLIP token required by checkfront_add_to_booking_session. It still omits pagination, rate limits, and result-count behavior.

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

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

Three tightly scoped sentences front-load the core purpose, then the mode-switching behavior, then the API mapping. No redundancy or filler, and the most decision-relevant fact (no dates = catalogue) is stated early.

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

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

For a 13-parameter tool with a nested object and no output schema, the description covers the essential dual behavior and summarizes what the rated response returns, which is the critical missing structured information. It is not exhaustive on pagination or limits, but nothing needed to choose and call the tool correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a cross-parameter semantic rule not captured in the schema: start_date/end_date/param together switch the response from catalogue to rated. That interaction meaning earns a point above baseline, though the remaining filter parameters are not elaborated.

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 enabled inventory items') and enumerates the types (tours, activities, rentals, rooms). It clarifies the two response modes and connects itself to checkfront_add_to_booking_session via the SLIP token, but does not explicitly differentiate from other list/get siblings such as checkfront_get_item or checkfront_get_availability_calendar.

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

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

Gives clear conditional guidance: no dates yields the plain catalogue, passing start_date (plus end_date/param) yields a rated response with availability and pricing. It does not state when to prefer an alternative tool or any exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description goes further by naming the fields surfaced and noting that partner accounts are included alongside staff, which is real behavioral context absent from the annotations.

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

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

Two short sentences: the first front-loads what is listed and what comes back, the second gives the downstream-consumption note and the backing endpoint. No filler.

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

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

With no output schema, the description compensates by enumerating the returned fields, and with no parameters there is nothing else to document. It also cites the underlying API endpoint for traceability, leaving no material gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds a semantic link by explaining that the returned account_id is the value consumed by CHECKFRONT_ON_BEHALF, tying the output to downstream use.

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 precise verb+resource ('List the staff (and partner) accounts on the Checkfront account') and enumerates the returned fields (ids, names, emails, login ids, enabled flag). No sibling tool lists staff accounts, so an agent can distinguish it immediately.

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 supplies a concrete usage hook: 'The account_id is what CHECKFRONT_ON_BEHALF takes,' telling the agent why it would call this tool. It does not state exclusions or alternatives, but no sibling overlaps this capability.

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 then adds real behavioral context beyond the annotations: matching is exact-only, non-unique fields such as name may return multiple results, and output lands in a `customers` object. It omits things like empty-result behavior, result caps, and pagination, keeping it short of a 5.

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

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

A single dense sentence front-loads the lookup keys and multiplicity caveat, then the result location. The trailing 'Checkfront: GET /api/3.0/customer' is vendor/endpoint traceability that adds little for an agent deciding how to call the tool, so it is not perfectly waste-free.

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 `customers` result object, and it covers the multi-result risk from ambiguous keys — the two things an agent most needs here. All four parameters are additionally documented in the schema, so nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100% and each parameter is already documented as an exact match in the schema, so the description's 'exact matches' framing largely restates structured data. Baseline 3 applies; the multiplicity note for name adds a little value but no format or syntax guidance beyond the schema.

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

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

States a specific verb and resource ('Look up customers') plus the exact lookup keys (email, full name, phone), so the agent knows precisely what the tool retrieves. It does not name the sibling checkfront_get_customer or any other alternative, 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?

The description implies the usage context by naming the searchable fields and noting that non-unique fields can return several matches, which hints at when a search (vs. a single-record get) is appropriate. However, it gives no explicit when-to-use/when-not-to-use guidance and never routes the agent to checkfront_get_customer for id-based retrieval.

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 available, the description carries useful extra burden: it declares the change is reversible by re-setting the prior status, that no payment is recorded, and that the account's customer notifications may fire. Auth requirements and any rate limits are unstated, but the stated side effects are exactly the kind of context annotations do 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?

A single tight paragraph front-loads the action and its effects; the status groupings, reversibility, payment exclusion and notification trigger each earn their clause. The trailing API endpoint is the only near-redundant element and it is short.

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-param mutation with no output schema, the definition covers action, reversible-by-design recovery, payment non-effect and notification behavior. It stops short of stating permission/auth needs or exactly what a status change does to downstream booking records (inventory holds, session membership).

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's bare code list by explaining what the codes mean operationally (PAID/PART = confirming, VOID/STOP = cancelling) and by noting that notify optionally triggers customer notifications.

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 (Set) and resource (a booking's status) and then disambiguates the status space by intent: confirm (PAID/PART), hold (HOLD/WAIT), cancel (VOID/STOP). An agent can distinguish this from siblings like check_in_booking or create_booking from the description alone.

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

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

Gives clear context for when to reach for it (confirming a pending booking, putting it on hold, cancelling) and a boundary condition ('Does NOT record a payment'), which implicitly routes payment work elsewhere. It never names an alternative tool such as check_in_booking, so the routing is not fully explicit.

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