Reservio MCP by usefulapi

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

Goes well beyond destructiveHint=true: it declares the operation as a write, warns that Reservio may notify the client, states it is not idempotent ('a second call books a second appointment'), and names the underlying POST endpoint. These are exactly the behavioral traits an agent needs before mutating state.

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

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

Single dense sentence stack, front-loaded with the 'WRITE:' marker and the slot-prerequisite before the side-effect warnings. No filler.

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

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

For a mutation with no output schema, it covers side effects, idempotency, prerequisite slot retrieval, and the API path. The one gap is that it never indicates what the agent gets back (e.g., a booking id), which matters for follow-up calls.

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 83%, so start/end/service_id/client/business_id are already documented, including the business_id default-to-login behavior. The description only implies service and start/end, adding no syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('create a real appointment booking for a service') plus temporal scope ('at a start/end time'), which cleanly separates it from the group-booking sibling. An agent knows exactly what is produced without opening the schema.

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

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

Explicitly tells the agent to source the time from reservio_get_booking_slots, establishing a prerequisite workflow. It does not explicitly rule out reservio_create_group_booking, so the alternative-selection guidance is clear but not complete.

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 destructiveHint annotation: it warns that the client may be notified, that a second call books a second seat (non-idempotent), and names the underlying endpoint POST /businesses/{businessId}/bookings. These are exactly the side-effect facts an agent needs before writing.

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 classification and the core action, then risk warnings, then 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?

Complete for a mutation with no output schema except that it never says what a successful booking returns (e.g., a booking id), which an agent chaining calls would want. All other decision-relevant facts are present.

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

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

Schema coverage is 67%; the description adds provenance for event_id (must come from reservio_list_events) and clarifies the seat-per-call semantics. It adds nothing about the nested client fields (name/email/phone), which remain schema-only.

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 ("book a client into an existing group event") and names the source for the event id (reservio_list_events). The "group event" qualifier distinguishes it from reservio_create_appointment_booking without the agent needing to compare schemas.

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

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

Gives clear preconditions: the event must already exist and its id comes from reservio_list_events. It also warns the call is not repeatable, which is a usage constraint. It stops short of explicitly routing individual (non-group) bookings to reservio_create_appointment_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?

readOnlyHint=true already covers the safety profile, and the description adds the underlying endpoint (GET /businesses/{businessId}/availability/booking-days), which is mildly useful context. It does not disclose the response shape (a per-day free/not-free flag), pagination, or how partial-day availability is treated, so it adds only modest value beyond annotations.

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

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

Two short sentences, front-loaded with the behavioral meaning before the API path. Efficient, though the raw endpoint line is marginally useful to an agent and slightly dilutes focus.

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 availability query with full schema coverage and no output schema, the description conveys the essential semantics: a per-day boolean availability result over a required date range for a service. Only the exact return structure and whether resource_id narrows the answer are 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 description coverage is 100%, so all five parameters including from/to format examples, service_id, business_id default, and resource_id are fully documented in the schema. The description's mention of 'range' and 'for a service' merely echoes those parameters without adding syntax or constraints, so baseline 3 applies.

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

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

States a specific verb and resource: for each day in a range, report whether any slot is free for a service. That cleanly separates it from reservio_get_booking_slots (which returns actual slots) and reservio_get_event_days, though neither sibling is named 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 by the purpose statement — an agent can infer this is the coarse day-level check to run before fetching slots, but the description never says when to prefer it over reservio_get_booking_slots or reservio_get_event_days, nor 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?

readOnlyHint=true already establishes this is a safe read, so the description only needs to add context. It adds the underlying endpoint (GET /businesses/{businessId}/availability/booking-slots) and the word 'free' (filtered to unbooked), but says nothing about pagination, slot granularity, or whether booked/blocked slots are excluded vs. flagged.

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 primary capability front-loaded, followed by workflow guidance. The trailing API endpoint reference is marginally useful for debugging but is the one element that doesn't strictly earn its place 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?

There is no output schema, so the description carries the burden of describing the return value. It says 'list free time slots' but not what a slot contains (start/end, resource assignment, capacity), which matters because the output feeds directly into booking creation. Adequate for a read tool, but leaves a real gap for a tool with no output schema.

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

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

Schema description coverage is 100%, so all five parameters (from, to, service_id, business_id, resource_id) are already documented with formats and defaults. The description only restates that the range is a date range and that resource_id narrows to one staff member; it adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

Specific verb + resource + scope: 'List free time slots for a service in a date range, optionally for one resource.' An agent immediately knows this is availability lookup rather than booking creation. It does not explicitly contrast with the close sibling reservio_get_booking_days, so day-level vs slot-level granularity must be inferred from the names.

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?

'Use before creating a booking' gives a concrete workflow position and implicitly routes to reservio_create_appointment_booking / reservio_create_group_booking. No explicit when-not or alternative-tool guidance (e.g., when to prefer get_booking_days or list_opening_hours) is given.

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

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

Annotations already declare readOnlyHint=true. The description adds useful context by listing the returned profile fields and the underlying GET endpoint, though it does not mention authentication, error behavior, or rate limits.

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

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

Two compact sentences with no waste. The resource and returned fields are front-loaded, and the API endpoint is supplementary but brief.

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

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

For a simple one-parameter read tool with no output schema, the description is nearly complete: it names the resource, key returned fields, and endpoint. Minor gaps remain around auth/error behavior, but they are not essential 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 coverage is 100%, and the schema already documents business_id including the default behavior. The description does not add parameter meaning beyond the structured schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get the business profile.' It also names the key fields returned, making clear this is the business-level profile tool rather than resource, service, coupon, or booking siblings.

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

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

Usage is implied by 'Get the business profile,' but there is no explicit when-to-use guidance, prerequisites, or comparison to sibling tools such as get_resource or get_service.

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

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

readOnlyHint=true already declares this is a safe read, so the description's main added value is mapping the operation to GET /businesses/{businessId}/coupons/{couponId}. It says nothing about not-found behavior, error responses, or the default business scoping that the schema hints at.

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

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

Two short sentences with the core action front-loaded and the API endpoint as supporting detail. Nothing is wasted and nothing important is buried.

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

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

For a simple two-parameter read with full schema coverage and a readOnlyHint, the definition is nearly sufficient: action, id-based lookup, and endpoint are all present. Only minor edge-case behavior (coupon not found, permission scope) 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% – both coupon_id and business_id are documented, including the login-default for business_id and the provenance hint from reservio_list_coupons. The description adds no semantics beyond restating the path variables, 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 ('Get one coupon by id'), and the singular 'one' implicitly distinguishes it from the plural list_coupons sibling. It does not name an alternative explicitly, so it falls 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?

Usage is only implied: an agent infers it should call this when it has a coupon id rather than when it needs to browse coupons. No explicit when-to-use, prerequisites, or 'use reservio_list_coupons to find ids' guidance appears in the description.

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

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

readOnlyHint=true already declares this as a safe read, and the description adds that the result is per-day open/closed plus the backing endpoint GET /businesses/{businessId}/availability/event-days. It does not describe what a day with no events looks like or whether closed days are omitted or flagged, which is the main remaining behavioral question.

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

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

Two short sentences, with the purpose front-loaded ahead of the API endpoint reference. The endpoint line is marginal for an agent but cheap and occasionally useful for error interpretation.

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 4 fully documented parameters, read-only annotations, and no output schema, the description covers what the tool does and its scope. It could say more about the shape of the per-day result, but the core decision-relevant information is present.

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

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

Schema description coverage is 100%: from/to formats, business_id default at login, and resource_id's link to reservio_list_resources are all documented in the schema. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb ('tell whether a group event is open for booking') and resource (each day in a range), and its focus on group events implicitly separates it from reservio_get_booking_days. It stops short of naming that sibling explicitly, but the resource and scope are unambiguous.

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

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

Usage is only implied: an agent can infer this is the per-day availability check for group events. There is no explicit when-to-use/when-not guidance and no pointer to reservio_get_booking_days or reservio_get_booking_slots as the alternative for appointment-based availability.

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

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

readOnlyHint=true already declares this is a safe read, and the description is consistent with that by citing GET. The REST path adds a little context but is essentially a restatement of the operation rather than new behavioral information (no error behavior for unknown ids, no auth/scope notes).

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, no filler: the human-readable purpose comes first, endpoint second. Every clause contributes.

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

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

For a simple read tool with full schema coverage and a readOnly annotation, the essentials are present. However, with no output schema, the description never indicates what a returned resource looks like or whether it errors on a missing id, leaving a real gap for an agent planning to consume the result.

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

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

Schema description coverage is 100%, including the default for business_id and the note that resource_id comes from reservio_list_resources, so the heavy lifting is already done. The description adds no parameter-level meaning beyond the schema, which is the expected baseline here.

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

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

States a specific verb and resource ("Get one resource") and clarifies domain ambiguity by defining a resource as a staff member or room, plus the id-based lookup mode. It does not explicitly distinguish itself from the sibling reservio_list_resources, but the singular/"by id" framing 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?

Usage is only implied: fetching a single resource when its id is known. There is no explicit statement about when to prefer this over reservio_list_resources or what to do if the id is unknown (the schema hints the id comes from the list tool, but the description itself gives no guidance).

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

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

readOnlyHint=true already declares this is a safe read, so the bar is lower. The description adds the underlying REST endpoint (GET /businesses/{businessId}/services/{serviceId}), which is genuinely useful context for constructing calls, but says nothing about error behavior for a missing id or what the business_id default means.

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

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

Two sentences, zero waste, with the primary purpose front-loaded ahead of the endpoint detail. Nothing could be removed without losing information.

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

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

For a simple two-parameter read with full schema coverage and a readOnlyHint, this is nearly complete. The only minor gap is the absence of anything about response shape or failure modes, but nothing essential to correct invocation 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 both parameters are already documented, including the default for business_id and where service_id comes from. The description adds nothing beyond what the schema provides, making the baseline 3 the correct score.

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

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

States a specific verb and resource ('Get one service by id'), which clearly separates it from the sibling list_services. It stops short of naming siblings explicitly, but the singular-vs-list distinction is unambiguous.

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

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

Usage is only implied: an agent infers this is the single-item lookup counterpart to reservio_list_services. The hint that service_id comes from reservio_list_services lives in the schema, not the description, and there is no statement about when to prefer list_services versus this 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, so the description doesn't need to establish safety. It adds meaningful context beyond that — the shape of returned fields and the webhookless/polling constraint — which materially affects how an agent should use it. It stops short of covering page-size behavior or what a filtered-empty result looks like.

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: the return shape and sort guidance come first, with the polling rationale and endpoint as supporting detail. 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 usefully enumerates the fields returned, and it covers the polling use case for a five-parameter list tool with a nested filter object. Pagination semantics (offset/limit interplay) are left entirely to the schema, which is a minor but real gap.

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

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

Schema description coverage is 100%, so all five parameters (sort, limit, filter, offset, business_id) are already documented in the schema. The description reinforces sort with the -createdAt example but adds no semantics the schema doesn't already carry, 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 bookings") and immediately identifies what each record contains — client name, state, cost, and linked event — which clearly separates it from the day/slot lookups and the create_* siblings. It also pins the underlying endpoint, so the agent knows exactly which API surface is being hit.

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 gives a concrete usage pattern: sort by -createdAt to see newest first, and poll this endpoint to detect new bookings since Reservio has no webhooks. That is a real when-to-use signal, but no explicit exclusions or named alternatives (e.g., booking-days vs. bookings) are given.

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

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

Annotations already declare readOnlyHint=true and the description confirms it by citing GET /businesses/{businessId}/coupons, so the safety profile is consistent. It adds no behavioral detail beyond that: no note on default ordering, page size behavior, or whether the response is a bare array versus a paginated envelope.

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 short sentence plus the underlying endpoint; the resource definition is front-loaded with zero filler. Slightly terse given how much pagination surface the tool has, but nothing is wasted.

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

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

For a paginated list tool with a nested filter object and no output schema, the description says nothing about return shape, total counts, or how paging terminates. Annotations cover safety and the schema covers inputs, but the agent is left to guess what a call actually yields.

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%, with sort, limit, offset, filter, and business_id all documented in the schema itself. The description adds nothing about parameter semantics, so the baseline 3 applies.

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

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

States a specific verb+resource ('List coupons') and parenthetically clarifies what a coupon is (credit or visit packages), which disambiguates the domain term. It does not explicitly distinguish itself from the sibling reservio_get_coupon, though the list vs. get verbs imply the split.

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

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

There is no guidance on when to use this versus reservio_get_coupon, nor any mention of paging strategy or prerequisites. Usage is only inferable from the verb 'List'.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the underlying REST endpoint and the set of returned fields, which is useful context. It says nothing about pagination behavior, sort/filter semantics, or result volume, so it earns a middling score rather than a high one.

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, front-loaded with the resource and covered event types, with the endpoint tucked at the end. No filler.

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

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

With no output schema, the description usefully names the returned fields (start, end, type, capacity), and the schema fully covers the five optional parameters. Minor gaps remain around paging defaults and how filter keys map to event attributes, but nothing an agent would trip over.

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% — sort, limit, offset, filter and business_id are all documented in the schema, including the descending-prefix convention and the JSON:API filter encoding. The description adds nothing beyond that, which is the baseline case.

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

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

Uses a specific verb+resource ('List calendar events') and enumerates the event kinds covered (appointments, group events, blocked time), plus the fields returned. It does not differentiate from siblings such as reservio_list_bookings, 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 description says what the tool does but never when to use it versus reservio_list_bookings or reservio_get_event_days, nor does it mention exclusions or prerequisites. Usage is only inferable from the name and resource.

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 genuine value beyond that by disclosing the underlying endpoint (GET /businesses/{businessId}/opening-hours) and the shape of the values returned (seconds from midnight), which tells an agent how to interpret the response 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, zero filler, with the semantically important detail (days and seconds from midnight) front-loaded before the API reference. Every sentence 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 present, the description usefully compensates by describing the returned fields and units. What remains uncovered is minor for a single-optional-parameter read tool, though a note on error/empty behavior would have completed 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?

Schema description coverage is 100% and there is only one optional parameter, so the schema already carries the semantics including the 'default: the business you entered at login' behavior. The description adds nothing about business_id, making the baseline 3 appropriate.

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

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

The description gives a specific verb+resource ('List the opening hours of the business') and clarifies the return shape (days plus start/end in seconds from midnight), which meaningfully disambiguates it from availability-style siblings like get_booking_days and get_booking_slots. It stops short of explicitly contrasting itself with those siblings, so a 4 rather than 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: an agent can infer this is the tool for business hours rather than bookable slots, but the description never states when to pick it over get_booking_days/get_booking_slots or what prerequisites exist. No exclusions or alternatives are named.

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 annotation carries the safety profile. The description adds the underlying API route and clarifies the resource domain, but says nothing about pagination defaults, result ordering, or what the response looks like.

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 the purpose front-loaded and no filler. The second sentence is mostly an endpoint restatement, which is useful routing context but slightly redundant with 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?

For a five-parameter, nested-filter, no-output-schema tool, the description is thin: it doesn't indicate that results are paginated, what fields resources expose, or how filters resolve. The readOnly annotation and full schema coverage keep it adequate rather than inadequate.

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%, with sort, limit, offset, filter, and business_id all documented in the schema itself. The description adds no parameter guidance, 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 bookable resources") and clarifies what counts as a resource (staff, rooms), which separates it from get_resource and list_services. It doesn't explicitly name the sibling alternatives, so it falls short of the top band.

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

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

Usage is only implied by the verb 'list' – there is no explicit statement of when to use this versus reservio_get_resource or reservio_list_rosters, and no mention of prerequisites or scoping. An agent can infer the intent but not the selection 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?

The readOnlyHint annotation already tells the agent this is a safe read, so the description's burden is lighter. It adds the underlying endpoint (GET /businesses/{businessId}/rosters) but says nothing about pagination behavior, default page size, or what a roster record contains.

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

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

Two short sentences with the purpose front-loaded and no filler. The trailing API-endpoint sentence is of marginal value to an agent but is at least compact.

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

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

With five optional parameters, a nested filter object and no output schema, the description should say more about the returned roster structure and paging defaults. Adequate to call correctly, but thin for the tool's complexity.

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 explains sort, limit, offset, filter and business_id precisely. The description adds no format or semantics beyond its vague 'per resource and date' hint, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List staff work schedules (rosters)') with the scoping qualifiers 'per resource and date', which distinguishes it from list_bookings, list_resources and other siblings. It stops short of naming a sibling explicitly, so it's 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?

There is no statement of when to use this tool versus alternatives such as reservio_list_resources or reservio_list_bookings, nor any prerequisite or exclusion. The phrase 'per resource and date' only faintly implies a filtering 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?

readOnlyHint=true already establishes the safe-read profile, so the description isn't burdened with that. It adds value by naming the returned attributes and the underlying API route, but says nothing about pagination defaults (the schema's default 50/max 100), total counts, or whether results are scoped to the business.

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 returned, the second anchors it to the concrete API endpoint. Zero filler and nothing redundant.

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

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

With no output schema, the description correctly supplies the shape of a result item (duration, price, capacity) and maps to the endpoint. All five optional parameters are covered by the schema, so the only gap is that pagination/result-set size behavior is left entirely to 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 description coverage is 100% and each parameter (sort, limit, offset, filter, business_id) is documented in-schema, including the login-business default. The description adds no parameter-level guidance, 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?

Specific verb+resource (list services), and it enumerates the fields returned (duration, price, capacity), so an agent knows what this yields. It does not differentiate from the sibling reservio_get_service, which shares the same resource — the singular/plural distinction is left implicit.

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 'services clients can book' — i.e., discover bookable services — but there is no explicit statement of when to call this versus reservio_get_service for a single record, and no exclusions or prerequisites mentioned.

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