Bookings, providers and customers in your BookingKoala store.
Scored across 35 tools
The BookingKoala tools mostly map to distinct resources and actions, and the browser-automation tools are granular but clearly differentiated. Minor overlap exists between cotlet_browser_open and cotlet_browser_navigate, between cotlet_upload_file and cotlet_browser_upload, and between cotlet_apps and cotlet_whoami, but descriptions make the intended use clear.
The domain tools consistently use verb_noun naming (list_bookings, get_customer, refund_charge), and the Cotlet tools share a clear cotlet_ prefix plus a cotlet_browser_* subfamily. The only deviations are dashboard and noun-only names such as cotlet_apps and cotlet_whoami, which are still readable.
At 35 tools, the surface is well above the range where a single server remains easy to navigate. The count is partly explained by combining a BookingKoala admin suite with a full browser-automation and platform suite, but agents still face a heavy selection burden.
Read coverage is broad across bookings, customers, providers, invoices, charges, drafts and dashboard data, with useful lifecycle actions like cancel, reschedule, assign, refund and resend. However, update/edit operations are largely absent, create_booking only duplicates an existing booking rather than creating one from scratch, and invoice creation/voiding is missing.
Assign a provider or team to a booking, or to its whole recurring schedule. Puts the provider on the booking, as Assign in the booking's sidebar does, and returns the booking as get_booking shows it. BookingKoala tells the provider about the job. A provider who is not available at that time is refused unless even_if_unavailable is true. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | Booking id from list_bookings. | |
| provider_id | Yes | Provider or team id from list_providers. | |
| whole_schedule | No | Assign every later booking of the recurring schedule too. Default: false. | |
| even_if_unavailable | No | Assign although the provider is not available then. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the destructive/openWorld annotations: BookingKoala notifies the provider about the job, unavailable-provider assignments are refused unless overridden, and the operation 'waits for the owner's approval' — a non-obvious asynchronous/approval trait. It does not say what happens to an existing provider assignment (replacement vs. rejection), which the destructiveHint makes relevant, 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?
Front-loads the core action and scope in the first sentence, then layers side effects and constraints. Every sentence contributes, though 'Waits for the owner's approval' is slightly clipped and could be clearer about what the caller observes.
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?
Covers the mutation's side effects (provider notification, approval wait), validation behavior, and return shape by reference to get_booking, which compensates for the absent output schema. The only gap is what happens to a previously assigned provider.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it ties whole_schedule to 'its whole recurring schedule' and explains the refusal behavior gated by even_if_unavailable. This reinforces schema semantics rather than merely repeating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (assign) and resource (provider/team to a booking or recurring schedule), and explicitly scopes it against get_booking ('returns the booking as get_booking shows it'). An agent can distinguish this from siblings like get_booking, list_providers, and reschedule_booking without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear operational anchor ('as Assign in the booking's sidebar does') and defines the eligibility condition: unavailable providers are refused unless even_if_unavailable is true. It does not name a sibling alternative or an explicit when-not-to-use case, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel one booking or its whole recurring schedule, without a cancellation fee. Checks the store's cancellation rules first (a store that requires a reason gets the 'Other' reason with your text), then cancels as Cancel in the booking's sidebar does, with no fee. Nobody is told unless notify is true. Cancelled bookings leave list_bookings. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| notify | No | Email the customer and providers about it. Default: false. | |
| reason | No | Why it is cancelled (kept on the booking). | |
| booking_id | Yes | Booking id from list_bookings. | |
| whole_schedule | No | Cancel the whole recurring schedule from this booking on. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond destructiveHint/readOnlyHint: no cancellation fee, an owner-approval gate that makes the call blocking, store-specific cancellation-rule handling with reason substitution, notification suppressed unless notify=true, and the post-condition that cancelled bookings leave list_bookings. That is exactly the mutation-side behavior an agent needs before firing a destructive call.
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 and scope, and every sentence carries information about behavior. The only waste is the duplicated fee statement ('without a cancellation fee' at the start and 'with no fee' later).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent, open-world mutation with no output schema, the description covers fees, approval, notification, rule-checking, and post-state. The one soft spot is what the call returns while awaiting owner approval – success vs. pending is left implicit.
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 semantics: notify governs whether anyone is told, reason feeds the store's required-reason flow (with 'Other' substitution), and whole_schedule extends cancellation forward from this booking. It just doesn't clarify reason length/format constraints.
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 (cancel a booking) plus the two scope variants: one booking or its whole recurring schedule. It also clarifies that no fee applies and that cancelled bookings drop out of list_bookings, which lets an agent distinguish this from reschedule_booking or get_booking 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?
Gives clear context for use: it pre-checks store cancellation rules, substitutes the 'Other' reason when a store requires one, and only notifies when notify is true. It stops short of naming an explicit alternative ('use reschedule_booking to move instead') or stating when-not-to-use, so it's clear but not fully routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, signed in but not connected), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | Only this app, e.g. skool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, non-destructive, non-open-world behavior. The description adds useful context beyond that: authentication requirements, additional cost signal ('Free'), the status categories the response will contain, and the fact that a console link accompanies a recommended user step.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is compact and front-loads the returned status information, with prerequisites stated briefly afterward. The status list is dense but each clause carries meaning, and there is little wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with one optional filter, full schema coverage, and annotations covering safety, the description supplies the important behavioral and return-value context an agent needs. Remaining gaps are minor, such as not stating whether omitting the filter returns all apps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one optional parameter, and the schema fully documents it as 'Only this app, e.g. skool.' The description does not mention the filter parameter at all, but with 100% schema description coverage 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 resource (the user's workspace apps) and the exact status dimensions returned: access granted/requested, Cloud Browser account state, and next step with console link. It is clear what the tool reports, though it does not explicitly name or contrast with the sibling cotlet_request_apps tool.
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 text gives prerequisites ('Free. Needs the user's Cotlet API key or sign-in.') but no when-to-use guidance or explicit alternatives. An agent must infer that this is the read-only counterpart to cotlet_request_apps, and there is no stated condition for selecting this tool over that sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clicks a link, button or other element of the current page in the user's BookingKoala Cloud Browser, by its number in the page's element list, and returns the URL and title after the click. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by stating that it acts as the user on that site, that certain button categories are refused, that each started minute of the session costs credits, and that the session ends on close or 3 minutes after the last call. This is exactly the kind of side-effect, safety-gate and billing context annotations cannot convey, and it is consistent with destructiveHint=true and openWorldHint=true.
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 and the return value, with safety refusals and session economics after. Slightly dense — the credit and idle-timeout sentence is operational boilerplate likely repeated across the cotlet_browser_* family — but every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation tool with full annotation coverage and no output schema, the description closes the remaining gaps: what it returns (URL and title), what it will refuse to do, and the session lifecycle/cost. Nothing an agent needs before invoking it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is fully documented as 'The element's number in the element list of the current page.' The description repeats that phrasing and only hints that the list must be obtained elsewhere, so it adds little beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (clicks) and resource (an element of the current page, addressed by its number in the element list) and names the return value (URL and title after the click). The element-number mechanism implicitly separates it from cotlet_browser_press, cotlet_browser_type and cotlet_browser_select, which act through other mechanisms, so an agent can pick correctly without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use ('current page in the user's BookingKoala Cloud Browser') plus explicit exclusions: pay/buy buttons and buttons on account or sign-in pages are refused. It does not, however, explicitly route the agent to siblings for navigation (cotlet_browser_navigate) or keyboard input (cotlet_browser_press), leaving that inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ends the session in the user's BookingKoala Cloud Browser: the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, idempotent, non-destructive, and closed-world behavior, yet the description still adds meaningful context: cookies persist, the browser sleeps rather than terminating, and the per-minute charge stops. It also discloses the return payload (minutes and credits), which is valuable given there is no 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?
A single sentence that front-loads the action and follows with consequences (cookies kept, sleep, billing stops) and return values. Every clause earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter session-termination tool with no output schema, the description supplies everything an agent needs: what it does, what state persists, that billing halts, and what it returns. Nothing material is left ambiguous.
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; the baseline for a parameterless tool is a 4. No additional parameter nuance is required or missing.
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 concrete verb ("Ends the session") and a specific resource ("the user's BookingKoala Cloud Browser"), which is unambiguous against the sibling set of navigate/click/read/open browser tools. There is no other close-session tool, so the agent can discriminate 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 clearly establishes the closing context within the browser tool family, implying use when the browsing task is done. It stops short of explicitly naming alternatives or conditions (e.g., "call after cotlet_browser_read/screenshot when finished"), so it lands just below the top mark.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wakes the user's BookingKoala Cloud Browser, a real Chrome hosted on Cotlet and signed in to BookingKoala as the user. Use it for what the BookingKoala tools do not cover. Opens url when given and returns the page's URL and title. The user watches every step live. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A public http or https address, e.g. https://example.com. In an app's browser, a page of that app. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: the browser is a real Chrome signed in as the user, the user watches every step live, every started minute costs credits, and the session auto-ends 3 minutes after the last browser call or on close. It also discloses the return value (page URL and title) with no output schema present. None of this is derivable from readOnlyHint/openWorldHint/idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with what the browser is and the routing rule, then invocation and return, then cost/lifecycle. No filler; each sentence carries a distinct fact an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a session-starting tool with no output schema and one optional param, the description covers identity/auth context, the usage boundary, the return shape, and the cost and auto-teardown lifecycle. Nothing material is missing to call it correctly or to avoid surprising the user with credit spend.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the schema already pins `url` to a URI, but the description adds that the URL is optional ('opens `url` when given'), which the schema marks only via required=[] and never explains behaviorally. That is a modest but real addition beyond structured data.
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 concrete verb and resource: wakes the user's BookingKoala Cloud Browser (a real hosted Chrome signed in as the user), and opens `url`. Scope is clear versus the BookingKoala domain tools via 'use it for what the BookingKoala tools do not cover'. It does not, however, distinguish itself from the sibling `cotlet_browser_navigate`, which an agent could easily confuse with 'open this URL'.
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 an explicit selection rule: use this for anything the BookingKoala tools (create_booking, get_customer, etc.) do not cover. That is a real routing rule, not boilerplate. It stops short of explaining when to call `cotlet_browser_open` versus `cotlet_browser_navigate`/`cotlet_browser_read`, which is the sibling boundary most likely to trip an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Presses one key on the current page in the user's BookingKoala Cloud Browser, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list. Returns the URL and title after it. Enter on account pages is refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the return payload (URL and title), the refusal rule for Enter on account pages, the credit cost per started minute, and the session lifecycle (ends on close or 3 minutes after the last call). The annotations carry only safety hints, so this behavioral detail is genuinely additive.
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 and outcome examples, then constraint, then return value, then cost model — a sensible ordering with no filler. The final sentence is long and packs cost plus session timeout together, which is slightly dense but each clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description supplies the return value, and it covers the operational facts an agent needs for a stateful, credit-metered browser session: refusal conditions, session expiry, and cost. Nothing material for 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 coverage is 100% and the enum already enumerates the 15 allowed keys, so the baseline is 3. The description adds real semantics by explaining what several of those keys accomplish in context (Tab advances fields, Enter submits, Escape dismisses dialogs, arrows move through suggestions), which helps an agent choose the right enum value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Presses one key on the current page... on the element that has focus') and immediately grounds it with concrete outcomes (Tab to next field, Enter to send, Escape to close a dialog). The focus-target wording separates it from cotlet_browser_click and cotlet_browser_type, which act on selectors or insert text.
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 usage context through key-by-outcome examples and a hard constraint ('Enter on account pages is refused'), which tells the agent when this call will fail. It does not explicitly route to alternatives like cotlet_browser_type for typing text or cotlet_browser_click, so it falls short of a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the current page of the user's BookingKoala Cloud Browser: its readable text, up to 20,000 characters, and a numbered list of its links, buttons and fields. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds a lot beyond them: field values, cookies and storage are never returned (a real privacy boundary), the 20,000-character cap, that truncation on long pages starts near the current scroll position, per-minute credit cost, and that the session dies 3 minutes after the last call. Those are exactly the operational facts an agent cannot infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with what is returned before the limits and the cost/session caveats. No filler, and the most decision-relevant facts (return contents, truncation, billing) come in that order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden itself and does so: it describes the shape (text + numbered element list), the size limit, and where truncation begins. Combined with the explicit exclusions and the session/cost rules, an agent has everything needed to call it and interpret 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?
The tool takes zero parameters, so there is nothing to disambiguate beyond confirming the call is argument-free — the baseline for a 0-param tool. The description correctly adds no parameter discussion and instead spends its words on behavior.
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 ('Returns the current page of the user's BookingKoala Cloud Browser') and enumerates exactly what comes back: readable text up to 20,000 characters plus a numbered list of links, buttons and fields. That enumeration is what separates it from cotlet_browser_screenshot and the interaction siblings, since an agent can tell it is the text-extraction read rather than a visual or mutating call.
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 description makes clear you get page text and an index of interactive elements, which suggests reading after cotlet_browser_navigate/open and before cotlet_browser_click/type. But it never names an alternative or states when to prefer cotlet_browser_screenshot, nor does it give preconditions such as needing an open session first. The credit-cost note is useful framing but not routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a JPEG image of the visible part of the current page in the user's BookingKoala Cloud Browser, with its URL and title: boards, canvases and layouts that the page text does not show. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds non-obvious operational details: every started minute of the session costs credits, and the session ends on close or 3 minutes after the last call. It also discloses the return shape (JPEG plus URL and title), which the annotations do not touch. This is context an agent could not derive from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first front-loads what is returned and why it matters visually, the second carries the cost and lifetime constraints. No restatement of the name or 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?
With no parameters and no output schema, the description carries the full burden and meets it: it explains the return value (image, URL, title), the visual-content motivation, and the session cost/lifetime. Nothing an agent needs to decide whether and when to call 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?
The tool takes no parameters and the schema has additionalProperties false, so there is nothing to mis-specify; the description correctly implies the call acts on the current browser page state rather than on caller-supplied input. Baseline 4 applies for a zero-parameter 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?
The definition states a concrete verb and resource: it returns a JPEG image of the visible portion of the current page, plus that page's URL and title. It also scopes the value proposition ('boards, canvases and layouts that the page text does not show'), which distinguishes it from the text-reading sibling without needing to open a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'that the page text does not show' signals the condition that makes a screenshot the right call over textual reading, giving clear usage context. It stops short of explicitly naming cotlet_browser_read as the alternative, so the routing is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scrolls the current page in the user's BookingKoala Cloud Browser with the mouse wheel, as a person does: down or up by screens viewport heights (default 0.8), to the top or the bottom, or until element element is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| element | No | Scroll until this element of the element list is in view. | |
| screens | No | How far, in viewport heights, for down and up. Default: 0.8. | |
| direction | No | Where to scroll. Default: down. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new operational context: per-minute credit cost and the session ending 3 minutes after the last call. It also discloses return values (URL, title, at_top/at_bottom) that no output schema provides. Minor gap: no statement about behavior when the target element never comes into view.
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 and modes in the first clause; the trailing sentence about credits and session expiry is extra but earns its place by preventing surprise costs. Slightly dense, but no dead 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?
Covers what it does, what changes (lazy-loaded content), what it returns, and session/cost lifecycle — enough to invoke confidently without an output schema. Left unaddressed are edge cases like a never-visible element or scroll limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are already documented, including the 0.8 default and the down default. The description restates those defaults and clarifies that `element` indexes the element list from a prior read, but adds little beyond the schema — 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 (scrolls) and resource (the current page in the user's BookingKoala Cloud Browser) and enumerates the exact modes: by screens, to top/bottom, or until an element is in view. An agent can distinguish this from cotlet_browser_click, navigate, and read 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?
Explains the operative use case — 'content that loads on scroll appears, and the next read lists it' — which tells the agent to scroll before reading rather than instead of reading. It does not explicitly name alternative siblings (e.g., use cotlet_browser_navigate to change pages), so it is a clear-context 4 rather than a routing 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Chooses an option of a drop-down list on the current page in the user's BookingKoala Cloud Browser, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| option | Yes | The option. | |
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds real value beyond them: return payload (URL and title), refusals for card fields/account pages, and credit cost with session termination (closed or 3 minutes after last call). It doesn't explain reversibility or failure modes, keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the verb and target, then layers returns, refusals, and cost in a compact way. It is dense and slightly run-on but every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param browser interaction with no output schema, it covers return values, safety scope, and cost/lifecycle. It omits how to obtain the element list (e.g., via cotlet_browser_read) and any browser-open/navigate prerequisite, a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description adds marginal meaning ('as read lists it (or its value)') but largely restates element-number and option-label semantics already present.
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 ('Chooses an option') on a specific resource ('drop-down list on the current page in the user's BookingKoala Cloud Browser') and how the target is identified. It is clearly distinguishable from siblings like cotlet_browser_click, type, and press.
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 clear context (current page, by element-list number and option label/value) and explicit exclusions ('Card fields and account pages are refused'). It stops short of naming which sibling to use instead when a dropdown is not involved, so it is strong but not fully routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Types text into a field of the current page in the user's BookingKoala Cloud Browser, by the field's number in the page's element list, and with submit presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The text to type. | |
| submit | No | Press Enter after typing, e.g. to search. | |
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructive/openWorld but say nothing about consequences. The description adds substantial context: it returns the URL and title afterward, sensitive fields and sign-in pages are refused, and the session bills per started minute and expires 3 minutes after the last call. That is exactly the operational and cost information an agent needs before invoking a state-changing open-world tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying distinct information: action, return value, refusal policy, billing/lifetime. The primary action is front-loaded and nothing is repeated from the schema verbatim.
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 supplies the return values (URL and title), and for a destructive open-world tool it covers refusal policy and session cost/lifetime. Nothing material 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 coverage is 100%, so element, text and submit are already documented in the schema. The description restates element addressing and submit-as-Enter, adding little beyond the schema, though it does clarify that text lands in a field rather than anywhere on the page. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Types text into a field of the current page') plus the addressing mechanism (field number in the page's element list) and the submit behavior. This cleanly separates it from cotlet_browser_click, cotlet_browser_select and cotlet_browser_press, which an agent would otherwise confuse with 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 a clear context of use (element-list addressing, optional Enter to submit) and an explicit exclusion: password, card and one-time-code fields and sign-in pages are refused and left to the user. It stops short of naming sibling alternatives (e.g. use select for dropdowns, press for keys), so the routing is clear but not fully complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Puts files into a file field of the current page in the user's BookingKoala Cloud Browser, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | The files. | |
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already flag destructive/openWorld/non-idempotent), the description discloses the return value ('Returns the URL and title'), hard limits (up to 10 files, 20 MB each), and the session billing/lifecycle model ('every started minute ... costs credits; ends 3 minutes after the last call'). That is exactly the extra operational context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action, followed by input formats, limits, and session cost. Dense but every clause carries operational information; nothing is wasted, though the session-credit sentence slightly crowds the core definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive write tool with an open-world browser context and no output schema, the description covers inputs, limits, return value, and session lifetime well. Minor gaps remain around failure behavior (what happens if the element is not a file input or a file exceeds limits), but the agent has what it needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description still adds value by explaining the two mutually exclusive file-reference shapes ({url} for online files vs {file_id} for files already in Cotlet) and by clarifying that 'element' is the element's number in the page element list, reinforcing the schema's intent.
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 ('Puts files into a file field of the current page ... or into the file picker an upload button opens'), which is far more precise than the bare title. It implicitly distinguishes itself from the sibling cotlet_upload_file by noting that file_id refers to a file 'uploaded to Cotlet first', but it never names that sibling outright.
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 describes the two invocation contexts (direct file field vs. upload-button picker), which gives useful context for when this tool applies. However, it does not explicitly say when to prefer cotlet_upload_file over this tool or what preconditions (e.g. an open browser session on the right page) must hold, leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.
| Name | Required | Description | Default |
|---|---|---|---|
| call_id | Yes | call_id from the earlier call |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes the status vocabulary and the polling context, but says nothing about behavior for an unknown or expired call_id, retention window, or whether repeated polling is rate-limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the resource and key, with the status set inlined rather than padded into separate sentences. The trailing 'answered with status pending or running' is slightly awkward phrasing but earns its place as scoping 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 one-parameter read tool with no output schema, the description supplies the crucial return-value information (the full status enum) that the structured fields omit. Only minor gaps remain, such as what accompanies the status in the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics. The description's 'by its call_id' merely restates the schema and adds no format or sourcing detail (e.g. where the call_id came from).
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 resource (an earlier Cotlet call) and a specific retrieval (its status, keyed by call_id), and enumerates every terminal and intermediate state so the agent knows exactly what it will get back. No sibling tool overlaps this resource, so the lack of an explicit 'not for X' does not create ambiguity.
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 closing clause scopes it to calls whose prior response was pending or running, which effectively tells the agent this is a polling tool rather than a general history lookup. It stops short of naming an alternative or saying what to do once a terminal status is reached.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | App slug the report is about, e.g. 'skool'. | |
| kind | Yes | bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else. | |
| tool | No | Tool or endpoint name, e.g. 'skool_list_members'. | |
| title | Yes | One line, e.g. 'skool_list_members stops after 50 members'. | |
| client | No | Agent or tool sending this, e.g. 'Claude Code'. | |
| call_id | No | call_id of the call that went wrong, if any. | |
| description | Yes | What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, so the description only needs to add context. It does: it states where the report goes, that error text and call_id are attached when available, that secrets are never included, and that an API key or sign-in is required. It does not mention what happens on duplicate submissions, consistent with idempotentHint=false but not explained.
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, front-loaded with the action and its goal, then the trigger scenarios, then the content and auth constraints. No filler and nothing repeated from the title or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers purpose, triggers, attached payload, secret handling and authentication, which is enough to call it correctly. It omits what the caller receives back or whether filing duplicates creates separate reports, a minor gap for a write 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%, so enum values for `kind` and field meanings for `tool`, `app` and `call_id` are already documented in the schema. The description adds only marginal meaning, clarifying that call_id and error text are picked up automatically when present, which is the baseline expectation given full schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Sends a report straight to the Cotlet team') and enumerates the concrete situations it covers: failed or wrong-data tools, blockers, missing tools/fields/apps. It stops short of explicitly distinguishing itself from the sibling cotlet_request_apps, which plausibly overlaps with the 'app the task needed and Cotlet lacks' case.
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?
Clear contextual triggers are given ('failed or returned wrong data', 'an error you could not get past', 'needed and Cotlet lacks'), which is enough for an agent to decide when to file a report. It offers no explicit exclusion or pointer to cotlet_request_apps / cotlet_get_call, so edge-case routing 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.
Requests access to apps for the user's workspace, as Request access in the console: a live app is granted at once, any other goes to the Cotlet team, who answer within 72 hours. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| apps | Yes | App slugs, e.g. ["skool", "substack"]. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: a live app is granted immediately, other requests go to the Cotlet team with a 72-hour response window, the operation is free, and authentication via Cotlet API key or sign-in is required. The mutation-like but non-destructive nature is consistent with 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?
Three tight sentences with the core action front-loaded, followed by outcome behavior, slug source, cost, and authentication. No wasted words.
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 request tool with no output schema, the description provides everything needed to call it correctly: what it does, how outcomes differ, where to get valid slugs, and what credentials are required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the apps parameter and slug examples. The description adds useful context by pointing to https://cotlet.dev/api/v1/apps as the canonical slug list, though it does not mention the maxItems limit.
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: request access to apps for the user's workspace. It distinguishes this from informational siblings like cotlet_apps and cotlet_balance by describing an action that submits an access request and explains the two possible outcomes.
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 clearly frames the tool as the programmatic equivalent of 'Request access' in the console, which implies when to use it. It does not explicitly say to use cotlet_apps first to discover slugs, so a small inference remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | File name, e.g. photo.jpg. | |
| content_type | No | MIME type, e.g. image/jpeg. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: it returns a one-time upload_url and file_id, requires an HTTP PUT to upload_url, enforces a 25 MB limit, states the URL works only once, and notes the Cotlet API key/sign-in requirement. These details are consistent with the non-read-only, non-destructive annotation profile and materially help the agent understand the workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The most important fact—what is returned and how it is used—is front-loaded in the first sentence. The remaining sentences cover upload method, size limit, one-time behavior, and auth without wasted words.
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, and the description fully explains the return values, the upload workflow, the file size constraint, one-time URL behavior, and authentication needs. An agent has enough information to invoke and chain this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both name and content_type documented with examples in the schema itself. The description does not add parameter-specific syntax or constraints beyond that, so the baseline score 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: it returns a one-time upload_url and file_id for a local file. It also clarifies the intended use cases (an image for a post, an attachment), but it does not explicitly distinguish this helper from sibling tools such as cotlet_browser_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: call this to obtain upload_url and file_id, PUT the file to upload_url, then pass file_id to any argument that accepts a file. It does not name when-not-to-use cases or alternative tools, so it falls short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds genuine value beyond them: it declares the call is credit-free ('Free') and that authentication via the user's Cotlet API key or sign-in is required, which matters for failure handling. It does not say what shape/format the response takes, but the field list largely compensates.
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 the substantive return contents, the second carries the cost and auth facts. No filler, no restatement of the title, and 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?
There is no output schema, so the description must carry the return contract — and it does, enumerating each field the agent will receive. Combined with the required-auth note, an agent has enough to call it correctly. Only minor gaps remain, such as how failures look when the key is missing or what access-status values are possible.
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 and the baseline of 4 applies. Nothing in the text conflicts with the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource — the Cotlet account identity for this connection — and enumerates exactly what comes back (email, workspace, access status, API key/OAuth client scope, callable apps, credit balance). That is far more specific than the bare 'who am I' title. It stops short of explicitly distinguishing itself from siblings like cotlet_balance and cotlet_apps, which overlap on the balance and app-list portions of the response.
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 context is implied rather than stated: an agent can infer this is the pre-flight identity/permission check, and 'Needs the user's Cotlet API key or sign-in' plus 'Free' tells it the prerequisites and that no credits are consumed. However there is no explicit 'call this before cotlet_apps or cotlet_balance to verify access' routing, and no stated conditions under which this tool should be skipped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new booking as a copy of an existing one: same customer, service and price. Copies the booking as Duplicate in its sidebar does. The copy is saved as a draft (list_drafts) with the same customer, address, service, extras and price; open form_url to pick the date and book it. Nobody is told until it is booked.
| Name | Required | Description | Default |
|---|---|---|---|
| from_booking_id | Yes | Booking to copy, from list_bookings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial context beyond the annotations: the copy is saved as a draft, it inherits customer, address, service, extras and price, form_url is needed to finalize the booking, and nobody is notified until it is actually booked. This clarifies state and side effects for a creation workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and practical, but it repeats the copied fields in two places ('same customer, service and price' and then 'same customer, address, service, extras and price'), which adds slight redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter create tool with annotations and no output schema, the description is complete: it explains the draft state, copied fields, next step via form_url, and notification behavior. An agent has enough information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single parameter is already well documented as the booking to copy from list_bookings. The description reinforces that it copies an existing booking but does not add new syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it starts a new booking as a copy of an existing booking. It also distinguishes the operation from a normal direct booking by explaining that it mirrors the Duplicate sidebar action and creates a draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the use case: duplicating an existing booking and then opening form_url to pick a date and book it. However, it does not explicitly name alternatives such as reschedule_booking or explain when not to use this copy workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
New customer in the store. BookingKoala emails them an invitation to set a password. Adds a customer as Add Customer in the admin does, with an optional address that becomes their default service address. BookingKoala emails the customer at once to set a password for the store's booking page, so use their real address. An email already in the store is refused. Returns the new customer as get_customer does. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| apt | No | Apartment or suite. | |
| city | No | City. | |
| Yes | Email address. BookingKoala sends the customer an invitation to set a password. | ||
| phone | No | Phone number, digits only for US numbers, e.g. 2125550147. | |
| state | No | State, e.g. New York. | |
| gender | No | Gender, optional. | |
| address | No | Street address, e.g. 540 W 28th Street, New York, NY, USA. | |
| country | No | Country, e.g. United States. | |
| zipcode | No | ZIP or postal code. | |
| last_name | Yes | Last name. | |
| first_name | Yes | First name. | |
| sms_notifications | No | Text the customer booking updates. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnly=false, destructive=true, openWorld=true) by disclosing the invitation email side effect, that the optional address becomes the default service address, that duplicate emails are rejected, and — most importantly — that the call 'waits for the owner's approval.' That pending-approval state is a behavioral trait an agent would otherwise not know. It stops short of describing what happens to partial failures or how long approval takes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action, but the invitation email is explained twice ('BookingKoala emails them an invitation to set a password' and again 'BookingKoala emails the customer at once to set a password for the store's booking page'), and the 'as Add Customer in the admin does' clause is filler. Roughly a third of the text could be cut with no loss.
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 12-parameter creation tool with full schema coverage and annotations present, the description covers the main things an agent needs: the email side effect, duplicate-email refusal, default-address behavior, the approval gate, and the return shape (via get_customer). It lacks any error taxonomy beyond duplicate email, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 12 parameters and the baseline is 3. The description adds one genuinely new fact — that the supplied address becomes the customer's default service address — but otherwise repeats the email/invitation semantics already present in the schema, so value beyond the schema is modest.
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 ('New customer in the store'), and the closing line ties it to get_customer, so an agent can tell it apart from get_customer/list_customers without opening a schema. The phrasing 'Adds a customer as Add Customer in the admin does' is circular and adds nothing, which keeps it from 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?
Offers concrete preconditions (an email already in the store is refused) and an explicit instruction ('use their real address'), which is real usage guidance. However it never states when to reach for this versus list_customers/get_customer, nor what to do after the call returns (e.g. that the record won't be active until approved) — guidance is implied rather than laid out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store totals for a date range: revenue, provider pay, bookings, ratings, referrals. Returns the figures of the admin Dashboard for the dates given (this month by default): revenue paid and pending, split into bookings, custom invoices and separate charges; what providers earned and what is still unpaid; booking counts, unassigned and cancelled included; ratings and referrals. Amounts are in the store's currency.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | YYYY-MM-DD, included. Default: last day of this month. | |
| start_date | No | YYYY-MM-DD. Default: first day of this month. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation, so safety behavior is covered. The description adds useful context beyond the annotations: the default date range, the exact buckets included, that unassigned and cancelled bookings are counted, and that amounts use the store currency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose in the opening sentence and then expands into return details, which is appropriate because there is no output schema. It is somewhat enumeration-heavy but not padded with irrelevant material.
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 explaining return values and does so thoroughly: revenue paid/pending, splits across bookings/invoices/charges, provider pay, booking counts, ratings, referrals, and currency. Annotations cover the safety profile. A small gap is the lack of explicit routing relative to sibling list 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 schema already documents the YYYY-MM-DD format and the first/last day of month defaults for start_date and end_date. The description repeats the default-date behavior but adds no format or semantic 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?
The description states a specific verb and resource: it returns/store totals for the admin Dashboard over a date range, and enumerates the metrics. That makes the purpose clear, but it does not explicitly distinguish this aggregate-summary tool from sibling list tools such as list_charges, list_bookings, or list_invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the description says it returns figures for the dates given, defaulting to this month. It never says when to choose this over the many list_* siblings, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One booking with its price breakdown, provider pay, notes and service. Reads a booking by id: date and arrival window, customer, address, assigned providers, the service parameters and extras, notes, the price breakdown (service total, discounts, tax, tip, final amount) and what the providers are paid for it.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | Booking id from list_bookings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered; the description's real contribution is disclosing the returned payload in detail, which matters because there is no output schema. It does not say what happens for a nonexistent or unauthorized booking id, leaving that behavior unstated.
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 a one-line summary of the returned record before the enumerated detail. Slight redundancy — 'price breakdown' and provider pay are named twice in quick succession — but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the necessary work of explaining the return shape, and a single-parameter read tool has little other complexity to cover. The remaining gap is failure/empty-case behavior for an invalid id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with 100% schema description coverage, so the schema carries the semantics ('Booking id from list_bookings'). The description restates 'by id' but adds no format, range or sourcing detail beyond what the schema already says; 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 ('Reads a booking by id') and enumerates exactly what comes back (date/arrival window, customer, address, providers, service parameters and extras, notes, price breakdown, provider pay). This clearly separates it from list_bookings, which returns the ids this tool consumes.
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 'reads a booking by id' framing plus the schema's 'Booking id from list_bookings' makes the retrieval-after-listing workflow clear. There is no explicit when-not guidance (e.g. use list_bookings to search, use reschedule_booking to modify), so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer: contact details, addresses, booking counts and bookings not charged yet. Returns the customer's profile as their page in the admin shows it: name, email, phone, saved addresses (address_id is what a booking or invoice for this customer uses), counts of upcoming and cash bookings, the bookings not charged yet (past ones included), gift cards received and the referral summary. Times of day are in the store's time zone.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | customer_id from list_customers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive, and closed-world behavior. The description adds substantial behavioral context beyond that: what the return payload contains, how address_id relates to bookings/invoices, that past uncharged bookings are included, and that times are in the store's time zone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then details the returned fields. It is somewhat dense and field-heavy, but every clause adds useful context and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining the response. It does so thoroughly, covering profile fields, addresses, booking counts, uncharged bookings, gift cards, referrals, and time-zone behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single customer_id parameter is documented in the schema as coming from list_customers. The description does not add further parameter-level meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines a single-customer retrieval and enumerates what is returned: contact details, addresses, booking counts, and not-yet-charged bookings. It distinguishes this from a list operation by saying 'One customer,' but does not explicitly name list_customers as the alternative.
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: fetch one customer by customer_id, likely after finding the ID via list_customers. However, there is no explicit guidance on when to use this instead of list_customers or create_customer, and no exclusions or prerequisite context beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One provider or team: contact, category, team members, reviews and payment logs. Returns the provider's profile as their page in the admin shows it: contact details, IC or W2 category, priority, scheduling permissions, the team's members and lead (for a team) or the teams it belongs to, customer reviews and the newest payment logs (what the store paid the provider). Payment logs come as BookingKoala records them.
| Name | Required | Description | Default |
|---|---|---|---|
| provider_id | Yes | provider_id from list_providers (a team too). | |
| payment_logs_limit | No | Newest payment logs to include, 1 to 50. Default: 20. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is read-only, idempotent, non-destructive, and closed-world. The description adds useful context about the returned data, including reviews and payment logs, but does not disclose notable behavioral details such as error behavior or whether all fields are always present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and generally efficient, but it repeats the same return contents: contact details, category, team members, reviews, and payment logs appear in both the first and second sentences. That redundancy reduces conciseness without adding 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?
With no output schema, the description carries the burden of explaining what is returned, and it does so in detail: contact info, category, priority, permissions, team relationships, reviews, and payment logs. It could be slightly stronger by connecting payment_logs_limit to the payment-log section, but the schema covers that parameter.
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 fully documents both provider_id and payment_logs_limit. The description reinforces that payment logs are included but does not add limit syntax, defaults, or other meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: retrieving one provider or team. It clearly defines the scope as a single profile rather than a list, but it does not explicitly name list_providers as the alternative and relies on the reader to infer that difference.
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 'One provider or team' and the detailed profile contents, which suggests this is the detail-view tool. However, there is no explicit guidance on when to use this instead of list_providers or how to obtain the provider_id beyond what the schema already says.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bookings of the store: upcoming, unassigned, completed, charge pending or declined. Lists bookings as the Bookings page shows them, newest schedule dates first within the filter, with the customer, address, assigned providers, total and whether it is charged. Filter by status, date range, a search on the customer, or one customer or provider. Cancelled bookings are not listed. Page with next_cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size. Default: 20. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Customer name, email or phone. | |
| status | No | Which bookings: upcoming (default), today, unassigned, completed, pending (charge pending), declined (charge declined), paused or all. | |
| end_date | No | Up to this date. | |
| start_date | No | From this date. | |
| customer_id | No | Only this customer's bookings. | |
| provider_id | No | Only this provider's bookings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine value beyond that — result ordering (newest schedule date first), the cancelled-booking exclusion, and what each row contains — but says nothing about limits on total result volume or behavior of cursor expiry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the resource and what is listed, then filters, then pagination. Slightly dense and run-on in the opening status enumeration, but every clause carries information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 optional parameters and no output schema, the description usefully compensates by naming the fields returned and the ordering, plus the pagination contract (next_cursor). However, since there is no output schema, it could have been more explicit about the response envelope and default page size.
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 every parameter (limit, cursor, search, status enum, date bounds, customer_id, provider_id) is already documented in the schema. The description restates the filter set at a high level and adds only the ordering/filter interaction, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource ("Bookings of the store") with an explicit enumeration of the statuses it covers and a description of the row shape it returns (customer, address, providers, total, charged). It is clearly distinguishable from the single-item sibling get_booking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete selection criteria: filter by status, date range, search, customer_id or provider_id, and states an explicit exclusion ("Cancelled bookings are not listed"). It does not name a sibling as the alternative for the cases it excludes or for single-booking lookup, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Charged bookings with their payments and refunds, as the Charges page lists them. Returns bookings that were charged, newest first, each with its payments: the booking charge, extras, tips, fees and refunds, with amount, tax, refunded amount and card. Filter by booking day and search by customer. BookingKoala gives no total: next_cursor is set while a full page comes back. booking_id and payment_log_id go to refund_charge. Empty until the store charges through a connected payment processor or marks bookings paid in cash.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 1 to 100. Default: 20. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Customer name, email or phone, or a booking id. | |
| end_date | No | Last booking day, YYYY-MM-DD. Default: no upper bound. | |
| start_date | No | First booking day, YYYY-MM-DD. Default: no lower bound. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe, idempotent read; the description adds ordering (newest first), the explicit absence of a total, and the pagination rule that next_cursor is set while a full page returns. The empty-state explanation is behavior an agent could not infer from schema or 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?
Front-loaded with what is returned and dense with useful facts, with no filler sentences. It is somewhat crammed into run-on clauses (e.g. the 'BookingKoala gives no total' phrasing), which slightly hinders scanability.
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 still conveys the return shape — per-booking payment entries with amount, tax, refunded amount and card — plus ordering, pagination and empty-state conditions. Nothing essential for 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 coverage is 100%, so limit, cursor, search and the date bounds are already documented; the description only restates 'filter by booking day and search by customer'. The pairing of booking_id/payment_log_id with refund_charge is the one bit of added meaning, but it is not tied explicitly to the search parameter.
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 — charged bookings with their payments and refunds — and anchors it to the Charges page concept, which separates it from list_bookings and list_invoices. It also names the follow-up tool (refund_charge) for the identifiers it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the prerequisite that makes the tool non-empty (a connected processor or cash-marked bookings) and routes the agent to refund_charge when it has a booking_id or payment_log_id. It stops short of explicitly contrasting with list_bookings/list_invoices for a given task, so it is clear context rather than 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.
Customers of the store, with email and phone; search by name, email or phone. Returns the store's customers as the Customers page lists them, newest first, active or deactivated. BookingKoala gives no total: next_cursor is set while a full page comes back. Use customer_id in get_customer.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 1 to 100. Default: 20. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Part of a name, email or phone number. | |
| status | No | active or inactive (deactivated) customers. Default: active. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), so the description focuses on non-obvious behavior: newest-first ordering, no total count returned, and the rule that next_cursor is only present when a full page comes back. Those cursor and ordering semantics are genuinely additive; it stops short of describing page-size edge behavior in detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with what the tool returns and scoped by the search fields. Every sentence carries information; the phrasing is slightly telegraphic ("BookingKoala gives no total") but never padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on the return-shape burden and does so adequately: ordered list of the store's customers, active or deactivated, no total, cursor only on full pages. It doesn't describe the customer object's fields beyond email and phone, a minor residual gap for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds meaning: search spans name, email or phone, status covers active or deactivated customers, and the pagination note explains that cursor is populated only for full pages rather than echoing the schema wording.
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 customers of the store) plus the fields carried (email, phone) and the search dimensions. It is clearly distinguishable from the sibling get_customer, which it explicitly names for single-record lookup.
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 routes the agent to get_customer for detail retrieval once a customer_id is known, which is a clear alternative-selection cue. It doesn't state exclusions (e.g., when not to search) or prerequisites, so it falls short of a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draft bookings and quotes saved in the store, not yet booked. Lists the drafts and quotes on the Drafts page: customer, date when set, total and whether it is a quote. create_booking leaves a draft here. Page with next_cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size. Default: 20. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Customer name or email. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds real value by enumerating the returned fields (customer, date when set, total, quote flag) and the pagination model ('Page with next_cursor'). That is useful read-behavior context beyond 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?
Three short sentences, front-loaded with the resource definition and followed by what is shown and how paging works. Slight awkwardness from the opening verbless fragment, but there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing the response, and it does so by listing the four fields shown per draft plus the next_cursor paging token. Combined with the create_booking lifecycle hint, an agent has enough to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, cursor and search are fully documented in the schema already. The description only echoes the cursor concept via 'next_cursor' and adds no new meaning about search semantics or default page size, 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?
The description names the specific resource (draft bookings and quotes) and scopes it precisely as 'not yet booked,' which implicitly separates it from list_bookings. The verb 'lists' is clear, and the mention that create_booking leaves drafts here further pins down what the records are.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent can infer this is how you browse drafts before converting them to bookings, and the reference to create_booking hints at the lifecycle. But there is no explicit 'use this when...' or exclusion naming list_bookings as the alternative for confirmed bookings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invoices of the store or of one customer, with payment status, total and amount due. Returns invoices as the Invoices page lists them, newest first: number, customer, booking or custom type, payment status (paid, unpaid, partially_paid, void, uncollectible), total, paid, amount due, issue and due dates. Filter by customer, payment status and issue dates (default: two years back to a year ahead), or search by number, email, name or phone. BookingKoala gives no total: next_cursor is set while a full page comes back. invoice_id goes to resend_invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 1 to 100. Default: 20. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Invoice number, customer email, name or phone. | |
| end_date | No | To this issue day, YYYY-MM-DD. Default: a year ahead. | |
| pay_status | No | Payment status filter. | |
| start_date | No | From this issue day, YYYY-MM-DD. Default: 2 years ago. | |
| customer_id | No | Only this customer's invoices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only and idempotent, and the description adds real operational detail beyond that: newest-first ordering, the exact default date window (two years back to a year ahead), and the pagination quirk that next_cursor is only set when a full page returns.
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, front-loaded sentences: purpose first, then return shape, then filters. The return-field enumeration is long but useful given there is no output schema; only minor redundancy between the field list and the filter list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does so: field list, ordering, status values, and pagination behavior are all disclosed, along with defaults for the optional date params.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes further by naming the enum values, expanding what `search` matches, and explaining cursor semantics ('next_cursor is set while a full page comes back') in a way the schema does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Invoices of the store or of one customer') plus the data it carries, and distinguishes itself from resend_invoice by naming that sibling and what it needs. An agent can tell immediately what this returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Spells out the three filter axes (customer, payment status, issue dates) and the four search fields, and routes to resend_invoice by invoice_id. It never states when NOT to use it (e.g., browse charges instead), so it stops short of full alternatives coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Providers (cleaners, technicians) and teams of the store, in priority order. Returns the store's service providers as the Providers page lists them, single providers and teams together; type team returns teams only. A team lists its members' provider ids, a provider the teams it belongs to and leads. BookingKoala gives no total: next_cursor is set while a full page comes back. Use provider_id in get_provider and when assigning a booking.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | all: providers and teams (default). team: teams only. | |
| limit | No | 1 to 100. Default: 20. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Part of a name, email or phone number. | |
| status | No | active or inactive (deactivated) providers. Default: active. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: results come back in priority order matching the Providers page, teams embed member provider ids while providers embed their team memberships and leadership, and there is no total count — next_cursor is set whenever a full page returns. That last detail is a non-obvious pagination quirk an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what the tool returns and packs a lot of useful detail into few sentences with no filler. Some phrasing is compressed to the point of being dense ('BookingKoala gives no total'), and the member/team relationship sentences could be one clause shorter.
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 return-shape burden and does so: item composition, ordering, cross-references between providers and teams, and pagination semantics are all covered. An agent has everything needed to call it and to decide what to do with the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining what the type switch actually changes in the payload (teams only vs. mixed) and tying cursor behavior to the full-page rule. It does not elaborate on search matching or the limit range, but those are already fully described in 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 the resource precisely (service providers — cleaners, technicians — and teams) and the ordering (priority order), and immediately clarifies the type=team variant. It also distinguishes itself from the get_provider and assign_provider siblings by naming when to use provider_id in those tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditions for the type parameter ('type team returns teams only') and the default status of active. It points to downstream use ('Use provider_id in get_provider and when assigning a booking'), which implicitly frames this as the discovery step, though it never explicitly states when NOT to call this versus get_provider.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refund a paid booking charge, extra, tip or fee to the customer's card, in full or in part. Refunds one payment from list_charges (payment_log_id and its booking_id) through the store's payment processor, as the Refund popup of the Charges page does. amount includes tax and defaults to what is not refunded yet; less than that is a partial refund. Cancellation and reschedule fees are refunded only in full. The customer is not emailed unless notify_customer is true. Refused before you confirm when the store has no payment processor, the payment is not paid or the amount is too large. A booking paid partly with a gift card or referral credit is refunded in the panel. Money goes back to the customer and cannot be taken back. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Amount to refund, tax included. Default: everything not refunded yet. | |
| reason | Yes | Refund reason. | |
| booking_id | Yes | Booking id from list_bookings. | |
| payment_log_id | Yes | payment_log_id of a paid payment, from list_charges. | |
| notify_customer | No | Email the customer about the refund. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and it adds real consequence context: 'Money goes back to the customer and cannot be taken back', the customer is not emailed unless notify_customer is true, and the call is refused before confirmation on three preconditions. It also discloses the confirmation/owner-approval gating, which no annotation expresses.
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 what it does and which payment it targets; nearly every sentence carries a distinct rule. It is dense and slightly long, and the paired statements 'By default you confirm each call' and 'Waits for the owner's approval' overlap enough to add mild ambiguity about the gating flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, money-moving tool with no output schema, it covers prerequisites, irreversibility, notification side effects, partial-refund math and approval gating. It does not indicate what a successful call returns or how to verify the refund landed, which is the one gap for a high-stakes mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so 3 is the baseline, but the description adds semantics the schema lacks: amount includes tax, defaults to the unrefunded remainder, and anything less is a partial refund, with the extra rule that fee refunds must be full. It also makes the notify_customer default consequence explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource set ('Refund a paid booking charge, extra, tip or fee'), states scope ('in full or in part') and the unit of work ('Refunds one payment from list_charges'). This clearly separates it from siblings like cancel_booking (cancels, does not move money) and list_charges (reads).
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 routes the agent: the payment must come from list_charges via payment_log_id plus its booking_id. It states when-not cases (no payment processor, payment not paid, amount too large, gift-card/referral-credit payments must be refunded in the panel) and the constraint that cancellation/reschedule fees are refunded only in full.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Postpone a visit of a recurring booking to the date of a later visit in its schedule. Works like Postpone in the booking's sidebar: the visit moves to one of the schedule's later visit dates, keeping its arrival time and price, and the booking comes back as get_booking shows it. A date outside the schedule fails with the list of allowed dates. One-time bookings cannot be postponed. Nobody is told unless notify is true. A store that charges a reschedule fee refuses the move here: charge it in the panel. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | New date: one of the later visit dates of the booking's recurring schedule. | |
| notify | No | Email the customer and providers about the change. Default: false. | |
| booking_id | Yes | Booking id from list_bookings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructive/openWorld/non-idempotent; the description adds substantive traits: arrival time and price are preserved, the return shape mirrors get_booking, notification is silent unless notify is true, the move waits for owner approval, and fee-charging stores are refused. That is far beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Six short sentences, front-loaded with what it does before the failure modes, and no filler. It runs slightly long, but each sentence carries a distinct constraint or behavior, so the density is justified.
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 stating the booking returns as get_booking shows it. Combined with the approval wait, fee refusal, and invalid-date behavior, an agent has everything needed to call this correctly or route elsewhere.
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 meaning: 'date' must be a later visit date of the schedule (semantic constraint, not just format), and 'notify' is framed as a consent-visibility switch ('Nobody is told unless notify is true'). Booking_id gains the get_booking return linkage.
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 ('Postpone a visit of a recurring booking') and the exact target ('the date of a later visit in its schedule'), which immediately separates it from cancel_booking, create_booking, and assign_provider. The sidebar analogy anchors the mental model.
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 enumerates the when-not cases: one-time bookings cannot be postponed, dates outside the schedule fail with the allowed list, and fee-charging stores must reschedule in the panel instead. Each exclusion names the condition that selects the alternative path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an invoice to its customer again by email, text or both. Sends an existing invoice from list_invoices to its customer again, as the invoice's Resend button does: by email (default) and, with sms true, a text with the invoice link. The invoice's CC and billing addresses get the email too. attach_pdf defaults to the invoice's own setting. The invoice itself does not change. The customer gets it at once. BookingKoala refuses some resends with a warning, for example a void invoice; the error carries its message. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| sms | No | Text the invoice link to the customer. Default: false. | |
| No | Email the invoice to the customer. Default: true. | ||
| attach_pdf | No | Attach the PDF to the email. Default: as the invoice. | |
| invoice_id | Yes | invoice_id from list_invoices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses that CC/billing addresses also receive the email, that attach_pdf defaults to the invoice's own setting, that the invoice data is unchanged, that delivery is immediate, that some resends are refused with the message in the error, and that each call is confirmed/waits for owner approval by default (toggleable). This is exactly the extra context the annotations cannot express.
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?
Purpose and channel defaults are front-loaded in the first two sentences, but the opening two sentences restate each other ('send ... again' / 'sends ... again, as the invoice's Resend button does'), costing some tightness.
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, yet the description covers delivery channels, defaults, side effects, refusal behavior and the approval gate — everything an agent needs to invoke and anticipate the result of this open-world, non-idempotent action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds semantics by explaining that email is the default channel, sms adds a text with the invoice link, and attach_pdf inherits the invoice's setting rather than a fixed default.
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: 'Send an invoice to its customer again by email, text or both', and it names the source sibling list_invoices, so an agent can distinguish it from list_invoices or send_quote 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?
States the precondition (an existing invoice from list_invoices) and the channel defaults, plus a concrete refusal case ('a void invoice'). It does not name an alternative tool or explicit when-not conditions, which keeps it 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.
Email a saved quote to the customer with a link to book it. Sends a quote from list_drafts as the Send quote popup does: saves the recipient and expiry date on the quote, then emails the store's Send quote template (or your subject and message) with the quote's booking link. email defaults to the quote's customer; expires_on to the saved date, else a month ahead. Only drafts saved as quotes can be sent; a plain draft is refused before you confirm. The customer gets the email at once. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Send to this address. Default: the quote's customer. | ||
| message | No | Email body (HTML allowed). Default: the store's Send quote template. | |
| subject | No | Email subject. Default: the store's. | |
| draft_id | Yes | Id of a quote from list_drafts. | |
| expires_on | No | Last day the customer can book it, YYYY-MM-DD. Default: as saved, else a month ahead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that the recipient and expiry date are persisted on the quote, that the customer receives the email immediately and irreversibly, that a non-quote draft is rejected before confirmation, and that each call requires confirmation/owner approval by default. These are exactly the side effects an agent needs before invoking a destructive, non-idempotent tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and keeps the confirmation/approval caveats at the end where they belong. A few clauses, notably the restated parameter defaults, duplicate the schema and could be trimmed.
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?
Covers the mutation, its side effects, the refusal path, and the human-approval flow, which is everything needed to call it safely. The only omission is what a successful call returns, which matters slightly given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents every default (email → quote's customer, expires_on → saved date else a month ahead, message → store template). The description mostly restates those defaults rather than adding syntax or edge-case meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Email a saved quote to the customer with a link to book it') and immediately identifies the source object ('a quote from list_drafts'), which separates it from every sibling in the list.
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 an explicit precondition ('Only drafts saved as quotes can be sent; a plain draft is refused before you confirm') and points to list_drafts for obtaining the draft_id, plus states that confirmation is on by default and can be switched off. There is no ambiguity about when this tool applies versus not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
cotlet_balancecotlet_browser_connectcotlet_browser_sessionsassign_providercancel_bookingcotlet_appscotlet_balancecotlet_browser_clickcotlet_browser_closecotlet_browser_connectcotlet_browser_navigatecotlet_browser_opencotlet_browser_presscotlet_browser_readcotlet_browser_screenshotcotlet_browser_scrollcotlet_browser_selectcotlet_browser_sessionscotlet_browser_typecotlet_browser_uploadcotlet_get_callcotlet_report_issuecotlet_request_appscotlet_upload_filecotlet_whoamicreate_bookingcreate_customerdashboardget_bookingget_customerget_providerlist_bookingslist_chargeslist_customerslist_draftslist_invoiceslist_providersrefund_chargereschedule_bookingresend_invoicesend_quoteManage Housecall Pro customers, jobs, estimates and leads; schedule and dispatch jobs.
Browse rental orders, customers, products and availability, and create bookings in Booqable.
Read Zenbooker jobs, customers, invoices and timeslots; add customers and job notes.
Read Mindbody classes, schedules, clients, staff and sales; book clients and appointments.
Add one secure layer between your agents and this server.