BookingKoala by Cotlet

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

The annotations already declare destructiveHint, openWorldHint, and non-idempotence, so the bar is lower. The description adds a genuinely useful behavioral fact absent from annotations: the assignment 'waits for the owner's approval,' which tells the agent the action is pending rather than immediate. It does not explain what gets destroyed or what happens when the provider is unavailable, but the approval-wait detail is substantive.

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

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

Two short sentences, zero filler, with scope and the approval-wait constraint front-loaded. Every clause earns its place.

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

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

For a destructive mutation with no output schema but rich annotations and full parameter documentation, the description covers scope and the approval workflow adequately. A note on the consequence of whole_schedule or the unavailable-provider override would round it out, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, with all four parameters documented inline including defaults and sourcing hints (list_bookings, list_providers). The description adds no syntax or semantics beyond the schema, so the 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+resource ('Assign a provider or team to a booking') and extends scope precisely ('or to its whole recurring schedule'). No sibling tool does assignment, so it is easily distinguished from cancel_booking, reschedule_booking, get_provider, etc.

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 usage is implied by the verb and scope but no explicit when/when-not guidance or alternative routing exists. It does not, for example, say to prefer reschedule_booking or get_provider when the provider is wrong.

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

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

Annotations already flag destructive=true and non-idempotent, so the safety profile is covered; the description adds genuinely new behavior: no cancellation fee is charged and the cancellation is gated on the owner's approval. It stops short of saying whether the call returns immediately in a pending state or blocks until approval resolves.

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

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

Two tight sentences that front-load the operation and its scope, with no filler. Every clause carries information the agent can use.

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 mutation with no output schema, the description covers the two surprises an agent most needs (no fee, owner approval) but leaves the response contract unclear: whether the booking is cancelled immediately, what status comes back while approval is pending, and whether the call can be retried after a timeout given non-idempotency.

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%, with each of the four parameters already documented in the schema, so the baseline is 3. The description adds only that a whole-schedule cancellation starts 'from this booking on', which is a helpful nuance but not a systematic explanation of parameter 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?

Names a specific verb (cancel) and resource (booking), and clarifies the two scopes it handles: a single booking or its whole recurring schedule. It never names a sibling such as reschedule_booking or get_booking, so differentiation is left to the reader, but the operation itself is unambiguous.

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

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

The description implies the use case (you want to cancel without a fee, possibly an entire series), but it gives no explicit when-to-use/when-not guidance and does not contrast with alternatives like reschedule_booking for a booking the user may want to move instead of kill.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), and the description adds real context beyond them: it is free, it requires the user's Cotlet API key or sign-in, and it enumerates the status fields returned. Auth and cost disclosure are exactly the kind of extra behavioral facts that earn credit here; transport/pagination is the only minor gap.

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

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

The return content is front-loaded in the first sentence, with cost and auth as short trailing clauses. It is dense but not padded; every clause (statuses, cost, auth) conveys distinct information.

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

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

For a read-only tool with annotations and no output schema, the description adequately describes what comes back (per-app access and browser-account state plus the required user step and console link) and states auth needs. The missing piece is any pointer to the related request/browser tools, but nothing essential to calling it correctly is absent.

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

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

With 100% schema description coverage and a single optional 'app' filter, the schema carries parameter meaning. The description never references the filter, so it adds nothing over the structured field; 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 states the resource (the apps in the user's workspace) and what is reported per app: access status, Cloud Browser account state, and next step. It does not name or distinguish itself from the closest sibling, cotlet_request_apps, so an agent must infer which one to call when it wants to request access.

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?

'Free. Needs the user's Cotlet API key or sign-in.' gives a prerequisite but not a when-to-use rule. There is no explicit routing to cotlet_request_apps (for requesting an app) or to the cotlet_browser_* tools (for acting once an app is connected), so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds non-obvious context beyond them: that the call costs nothing ('Free') and that authentication is required, which are genuine behavioral facts an agent needs.

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

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

Three short sentences with the main purpose front-loaded and no padding. The 'Free.' fragment is terse but conveys a meaningful fact efficiently.

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

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

For a zero-parameter, read-only lookup with no output schema, the description covers what it returns, what it costs, and what auth it needs. Only minor gaps remain (e.g., currency/format of the balance), which is acceptable at this complexity.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify and it does not attempt to misdescribe inputs.

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 specific resource returned: the user's current credit balance. The verb ('get'/'retrieve') is implied rather than stated, and it doesn't differentiate from cotlet_whoami or other cotlet_* account tools by name, but the resource is unambiguous.

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

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

'Free' signals there is no cost/credit consumption to calling it, and the auth prerequisite ('needs the user's Cotlet API key or sign-in') tells the agent what is required before calling. There is no explicit when-to-use vs. alternative guidance, leaving usage implied.

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

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

Beyond the destructive/openWorld/non-idempotent annotations, it discloses that the tool acts as the user on the site, that certain action classes (payment, account/sign-in) are blocked, what is returned after the click, and the billing model with a 3-minute idle expiry. These are exactly the operational constraints 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?

Four sentences, all load-bearing: action, side-effect return, refusal policy, and cost/lifetime. The final sentence packs two distinct facts (credit cost and 3-minute idle expiry) into one long clause, which slightly hurts 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 covers the return value (URL and title), the side-effect profile, refusal conditions, and the session/cost lifecycle. An agent has everything needed to decide and invoke correctly.

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

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

The single parameter is fully documented in the schema (100% coverage), and the description's 'by its number in the page's element list' merely restates the schema text. No extra guidance on how to obtain valid element numbers, 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?

States a specific verb (clicks) and resource (a link, button or other element of the current page in the user's browser) plus the addressing mechanism (its number in the element list) and the return (URL and title). This clearly separates it from siblings like cotlet_browser_press, cotlet_browser_type, cotlet_browser_select and cotlet_browser_navigate without needing to name them.

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 explicit exclusion rules: pay/buy buttons and buttons on account or sign-in pages are refused, which tells the agent when this call will fail. It also frames the cost/session lifecycle (credits per started minute, session ends 3 minutes after the last call), but it never explicitly routes the agent among alternatives such as press vs select vs type for a given widget.

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

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

Adds substantial detail beyond annotations: cookies are retained, the browser sleeps, billing stops, and the tool returns session minutes and credits. This is consistent with destructiveHint=false because no cookies or session history are described as destroyed.

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

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

The description is a single front-loaded sentence that states the action, side effects, and return value without filler. Every clause contributes useful invocation context.

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 close tool with no output schema, the description is largely complete: it explains side effects and return values and aligns with the annotations. The only gap is the undefined `app` reference, which slightly undermines clarity.

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 schema has zero parameters and full coverage, which normally supports a baseline of 4. However, the description references `app` even though no such parameter exists in the input schema, creating a small ambiguity about how app scope is selected.

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: ending the browser session on Cotlet, with app-specific scope noted. This distinguishes it from siblings like cotlet_browser_open, cotlet_browser_connect, and cotlet_browser_sessions without needing their 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?

The description implies when to use it by explaining that the per-minute charge stops, but it does not explicitly contrast this with cotlet_browser_sessions or explain when not to close a session. Usage is inferable rather than stated.

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

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

Goes well past the annotations: it discloses that only one tab exists, that new tabs are refused, that the user watches live, that credits accrue per started minute of an open connection, and that a Cotlet API key or sign-in is required. These are exactly the operational facts an agent needs before opening a metered, user-visible session, and nothing contradicts the declared hints.

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 the action and return value, then constraints, then cost and auth. Minor awkwardness in "It works in one open tab, the app's:" but no sentence is wasted.

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

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

Covers return value, auth, cost, and tab restrictions, which is strong for a tool with no output schema. The gap is the missing link between "one app" and the zero-parameter schema: an agent is never told how the target app is chosen, nor that cotlet_browser_close should be called to stop the metered session.

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

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

The tool takes zero parameters, so the 4 baseline applies. The description adds the useful note that the browser is tied to "one app" and signed in as the user, which is context the empty schema cannot convey, though it never explains how that app is determined.

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?

A specific verb and resource ("Wakes the user's Cloud Browser") plus a concrete return value (cdp_url) makes the operation unambiguous. It distinguishes itself from interaction siblings like cotlet_browser_click/navigate by saying it hands over a CDP WebSocket, but it never names the closest alternative (cotlet_browser_open) so the boundary is inferred rather than stated.

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 CDP client full control" implies the use case (you need raw CDP rather than the click/type/navigate helpers), and the auth/cost constraints hint at prerequisites. However, there is no explicit when-to-use versus cotlet_browser_open or cotlet_browser_sessions, and no when-not-to-use guidance despite a crowded browser sibling family.

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

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

Annotations already cover the read-only, non-destructive, open-world profile, so the description is not obligated to repeat that. What it adds is genuinely useful and non-obvious: billing behavior (every started minute costs credits) and session lifetime (ends on close or 3 minutes after the last call), which no annotation conveys.

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, each carrying distinct information: what it does, the app-browser scoping rule, and the cost/session-lifetime caveat. No filler and the core action is front-loaded.

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

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

There is no output schema, and the description compensates by stating it returns the resulting URL and title. Session termination and credit cost are covered. Only failure behavior (invalid URL, non-public address, cross-app access) and the distinction from cotlet_browser_open are left unstated.

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

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

With a single parameter at 100% schema description coverage, the schema already fully documents the url format and its app-browser meaning. The description restates the http/https constraint but adds no format, validation, or edge-case detail beyond the schema.

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

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

The description gives a concrete verb and resource ("Opens a public http or https address in the user's browser on Cotlet") and notes the return value (final URL and title). It clarifies the app-scoped variant ("An app's browser opens only that app's pages"), though it never distinguishes itself from the closely named sibling cotlet_browser_open, leaving some 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?

It implies usage by constraining the address to public http/https and explaining the app-browser scope, but never states when to pick this over cotlet_browser_open, cotlet_browser_connect, or cotlet_browser_sessions. The agent must infer the routing from name similarity alone.

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

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

The annotations only declare read-only, open-world, non-idempotent and non-destructive. Beyond them, the description discloses that the user watches every step live, that every started minute costs credits, and that the session ends on close or three minutes after the last call. That billing and expiry model is exactly the context an agent needs before invoking the 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 dense sentences with no filler, and the core identification of what is being opened comes first. The lifecycle/cost details are clustered at the end, which reads a bit run-on but is still well-ordered.

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 appropriately states that the page URL and title are returned, and it covers cost and session expiry. The remaining gaps are the error behavior and routing to related session tools.

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

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

Schema coverage is 100%, so the single url parameter is fully documented in the schema, and the baseline is 3. The description does explain the two browsing contexts (the user's signed-in browser versus an app's browser), but it refers to an `app` parameter that does not exist in the schema, which can confuse an agent about what it can pass.

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: it wakes the user's own hosted Chrome on Cotlet and opens a URL. That is clear and concrete. However, it never contrasts itself with siblings like cotlet_browser_connect or cotlet_browser_navigate, which an agent must distinguish when starting a browsing session.

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 agent can infer that this is the entry point for starting a browsing session, and the closing sentence hints at session lifecycle. But there is no explicit 'use this when' versus connect/navigate, nor any guidance on whether to open the browser before calling click/type/read.

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

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

Goes well beyond the annotations (destructive, openWorld, non-idempotent) by disclosing a safety guardrail (Enter refused on account pages), the return payload (URL and title after the press), and the billing/session model (every started minute costs credits, session ends on close or 3 minutes after the last call). Those are exactly the non-obvious traits an agent needs before deciding to act.

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 front-loaded sentences: action and scope first, key semantics second, then constraints and side effects. No filler, and the credit/session warning is placed after the operational content where it belongs.

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 one enum-constrained parameter and no output schema, the description still names the return value, the refusal case, and the session lifetime. 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% with a fully enumerated key list, so the baseline is 3; the description adds real meaning by mapping keys to intents (Tab to next field, Enter to send, arrows for suggestion lists), which the bare enum does not convey.

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 in the user's browser on Cotlet') and scopes it to the focused element. The concrete key examples (Tab, Enter, Escape, arrows) separate it cleanly from cotlet_browser_type and cotlet_browser_select without needing their 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 concrete when-to-use guidance per key ('Tab to the next field, Enter to send, Escape to close a dialog or pop-up') plus an explicit refusal rule ('Enter on account pages is refused'). It never explicitly says when to prefer cotlet_browser_type or cotlet_browser_select instead, so it stops short of full alternative routing.

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

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

Adds significant behavioral context beyond annotations: limits (20,000 chars), exclusions (field values, cookies, storage), scroll-relative start on long pages, and cost model (credits per started minute, session ends after 3 minutes idle or on close). No contradiction with readOnly/idempotent hints.

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, front-loaded with what the tool returns, then limits, scroll behavior, and cost. Every sentence earns its place and no waste.

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, but the description fully explains return values (text, numbered list) and key operational details (size limits, exclusions, cost, session lifetime). Complete for a read 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?

Zero parameters, so baseline is 4. The description need not explain parameter semantics; it correctly focuses on return behavior and constraints instead.

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

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

States a specific verb ('Returns') and resource ('current page of the user's browser on Cotlet'), and enumerates what is returned (readable text, numbered list of links/buttons/fields). This clearly distinguishes it from sibling browser tools like screenshot or click.

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?

Implies usage (read the page's text and interactive elements), but provides no explicit when-to-use guidance or alternatives among the many browser tools (e.g., screenshot, navigate). An agent must infer the appropriate context.

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

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

Beyond the annotations (all of which it is consistent with), the description discloses two things an agent could not otherwise know: cost ('Every started minute of the session costs credits') and session lifecycle ('ends when closed or 3 minutes after the last call in that browser'). For a metered, session-bound tool this is exactly the right kind of added context.

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

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

Two dense sentences; the core output is front-loaded before the cost/lifecycle caveats. The colon-introduced list ('boards, canvases and layouts') is slightly awkward but each clause carries real information rather than restating the title.

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

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

With no output schema and no parameters, the burden falls on the description, and it covers output form, cost, and timeout. It does not state prerequisites (an active browser session) or what happens when no browser is connected, which is the main remaining gap for a session-scoped 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?

There are zero parameters, so no parameter semantics are required — the baseline for a parameterless tool applies. The description correctly adds nothing spurious about inputs.

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 ('Returns a JPEG image of the visible part of the current page') and even flags the return payload as URL + title. The clause 'boards, canvases and layouts that the page text does not show' indirectly distinguishes it from cotlet_browser_read, but it never names that sibling, so the differentiation is inferred rather than stated.

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

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

The phrase 'that the page text does not show' gives a usable heuristic for choosing screenshots over the text-reading sibling. What is missing is an explicit instruction such as 'use cotlet_browser_read for text' or a note that a browser session must already be connected via cotlet_browser_open/connect.

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

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

Goes well past the annotations by disclosing the cost model ('every started minute of the session costs credits'), the session lifecycle ('ends when closed or 3 minutes after the last call'), the implicit lazy-load side effect, and the exact return payload (URL, title, at_top, at_bottom). These are operational facts an agent cannot get from readOnly/idempotent hints alone.

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

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

One dense but front-loaded paragraph: mode enumeration first, then side effect/return, then billing. Every sentence carries information, though the billing clause is appended to a long sentence and could have been separated for 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?

No output schema exists, and the description compensates by naming the returned fields and their meaning (at_top, at_bottom). Combined with the three-mode explanation and session-cost warning, an agent has everything needed to call this correctly on the first attempt.

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 cross-parameter meaning the schema does not, namely that `screens` describes distance for the down/up modes while `element` selects the scroll-until-visible mode. It restates the 0.8 default and the direction set, which is mildly redundant with 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?

Starts with a specific verb+resource ('Scrolls the current page in the user's browser') and enumerates the three distinct modes of operation (by screens, to top/bottom, until element). An agent can distinguish it from siblings like cotlet_browser_read or cotlet_browser_navigate without opening any schema.

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

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

The phrase 'Content that loads on scroll appears, and the next read lists it' effectively tells the agent when to use this tool (to reach lazy-loaded content, then call cotlet_browser_read). It does not explicitly name a when-not condition or state that element-based scrolling supersedes the screens/direction parameters, so the routing is clear but not exhaustive.

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

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

Annotations only flag the operation as destructive, non-idempotent, and open-world; the description goes well beyond that by disclosing the return payload (URL and title after selection), the refusal of card fields and account pages, and the credit/session economics including the 3-minute inactivity timeout. That is exactly the kind of context an agent needs before spending money and mutating page state.

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

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

The core action is front-loaded in the first clause and each following sentence carries distinct information (return values, refusals, billing). It is dense rather than wasteful, though the session-cost sentence is boilerplate that inflates the definition relative to the two-parameter operation.

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 what is returned, what is blocked, and the session lifecycle cost, which is nearly everything an agent needs. The one remaining gap is what happens on an unsuccessful match (error vs. silent no-op), which matters given destructiveHint=true.

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

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

With 100% schema coverage, the schema already documents both parameters, so the baseline is 3. The description does add a little meaning by clarifying that 'option' can be matched by the label as the list renders it or by its value, but it says nothing about partial matching, case sensitivity, or failure behavior for an unmatched label.

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 ('Chooses an option') and resource ('drop-down list on the current page') and scopes it to Cotlet's browser session, which cleanly separates it from navigation or screenshot siblings. It does not explicitly name the neighboring tools (click/type/read) that an agent might confuse with selection, so it stops just short of full differentiation.

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

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

'On the current page' establishes the precondition that a page must already be loaded, and 'Card fields and account pages are refused' gives an explicit when-not boundary. It stops short of a 5 because it never names the alternative action (e.g., use click or type when the element is not a select).

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

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

The description adds meaningful behavior beyond the annotations: it discloses the authentication requirement, that costs and minutes are reported, that only still-valid cdp_url links are returned, and that closing revokes unused links. This is consistent with destructiveHint=true and readOnlyHint=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?

The description is compact and front-loads the main behavior, with the close behavior following immediately. The phrase 'of one app or of all' is unnecessary and confusing given the one-parameter schema, but overall there is little waste.

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 low-complexity tool with rich annotations and no output schema, the description covers the main return data and authentication. The unresolved 'one app or all' scope is a real gap because the schema cannot express app selection, leaving the agent unsure how to interpret that claim.

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 close parameter is already documented. The description adds that close=true ends connections and takes back unused links, but it also mentions 'of one app or of all' even though the schema exposes no app-targeting parameter, which creates ambiguity rather than clarity.

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 identifies the resource as Cloud Browser sessions and explains that it exposes cost, minutes, and valid cdp_url links, with an optional close behavior. It does not explicitly distinguish itself from sibling tools such as cotlet_browser_close or cotlet_browser_connect, and the opening verb 'Open' is slightly ambiguous.

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

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

It gives a useful condition for the close parameter ('With close: true') and states the authentication prerequisite. However, it does not explain when to use this tool versus cotlet_browser_close or other browser siblings, and the 'of one app or of all' scope is not actionable through the schema.

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

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

Goes well beyond the annotations: it discloses the return value (URL and title after typing), a security refusal policy for sensitive fields and sign-in pages, a credit cost per started minute, and session lifetime ('ends when closed or 3 minutes after the last call'). The mutation/destructive framing 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-loads the action and addressing scheme, then layers behaviour, refusals and cost in three tight clauses. The billing sentence is slightly off-topic for a typing tool but is genuinely useful context, so only a minor deduction.

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, open-world browser mutation with no output schema, the description covers the action, how elements are addressed, the return value, safety refusals, and session/cost lifecycle — everything an agent needs to call it without surprises.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description largely restates them (`submit` presses Enter, element numbering from the page's element list). Baseline 3 is appropriate; it adds no constraints or gotchas beyond the schema.

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

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

States a specific verb and resource ('types text into a field of the current page') plus the addressing scheme ('by the field's number in the page's element list'), which cleanly separates it from siblings like cotlet_browser_press, cotlet_browser_select and cotlet_browser_click.

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 when-to-use context via the `submit` note ('presses Enter after typing, e.g. to search') and an explicit when-not: password, card, one-time code fields and sign-in pages are refused and left to the user. It does not name the sibling to use instead for keystrokes like Tab/Escape, so it stops just short of 5.

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

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

Annotations already flag destructive, open-world, non-idempotent behavior, and the description adds real value on top: accepted file source shapes, the 10-file / 20 MB limits, the returned URL and title, and the per-minute credit cost with the 3-minute idle timeout. It does not say what happens on partial failure or whether existing field content is replaced, which keeps it short of a 5.

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

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

Two dense sentences, purpose and input shape front-loaded, with cost/session policy last. Every clause carries information, though the credit-and-timeout clause sits somewhat awkwardly in a tool-purpose description.

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

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

With no output schema, the description correctly states the return value (URL and title), and it covers input forms and limits. The main gap is the missing reference to how a browser session must already exist and how this differs from cotlet_upload_file.

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 restates the url/file_id alternatives and the element-number meaning that the schema already documents, adding limits (10 files, 20 MB) but no genuinely new semantics such as how the element list is obtained or what happens if element is not a file input.

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

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

The description gives a specific verb and resource ('puts files into a file field of the current page in the user's browser'), plus the targeting mechanism (element number). It distinguishes itself from generic upload behavior by naming the browser/session context, but it never contrasts itself with the sibling cotlet_upload_file, which an agent could easily confuse it with.

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 browser-session framing and the note that the session ends on close or 3 minutes after the last call imply when this tool fits, but there is no explicit 'use this instead of cotlet_upload_file when...' guidance, and no prerequisites (e.g. needing an open browser session from cotlet_browser_open/connect) are stated.

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

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

Annotations already declare readOnlyHint=true, 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.

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.

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.

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.

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.

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety and repeat-call behavior are covered. The description adds real value by enumerating what is copied (customer, service, price), but it leaves the most consequential unknown silent: whether the date/time is copied, and whether the new booking is immediately charged. The deliberate omission of date from the copy list is ambiguous rather than clarifying.

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

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

One sentence, zero filler, with the copy semantics front-loaded immediately after the verb. Nothing could be removed without losing information.

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

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

For a one-parameter creation tool with annotations present, the definition is close but not sufficient: with no output schema, an agent is not told what comes back (presumably a new booking ID needed for follow-up calls), and the copied date/time is unstated. Both gaps affect whether the agent should call it at all.

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

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

With a single parameter and 100% schema description coverage, the schema already explains from_booking_id and even points to list_bookings. The description explains what copying means semantically but adds no format or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Start a new booking") and narrows the semantics to a copy operation with the three fields that carry over. An agent can distinguish it from reschedule_booking or cancel_booking, though no sibling is named explicitly.

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

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

Usage is only implied: the required from_booking_id signals that an existing booking must be found first. There is no explicit guidance on when to copy versus build a booking another way, nor an exclusion such as "to move an existing booking, use reschedule_booking instead."

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

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

Annotations already declare this is a non-idempotent, destructive write. The description adds genuinely new context: BookingKoala emails an invitation to set a password and the customer waits for owner approval. It omits duplicate-email handling and what happens if approval is denied, but the side-effect disclosure goes well 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, side effects front-loaded after the core action, and zero filler. Every sentence contributes a distinct fact.

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 mutation with no output schema, the description covers the invitation email and approval workflow but never says what is returned (e.g., customer ID) or how approval interacts with the created record. Adequate but with clear gaps for an agent planning a create-then-verify flow.

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% across all 12 parameters, so the schema carries the parameter meaning. The description only echoes the email-invitation behavior already documented in the email property, adding no format or constraint details beyond it.

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 makes clear this creates a customer ('New customer in the store') and names the platform's follow-on behavior. It is distinguishable from get_customer/list_customers siblings, though the verb+resource framing is telegraphic rather than explicit.

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

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

No guidance on when to use this versus alternatives (e.g., list_customers to check for an existing record first) or prerequisites such as owner approval state. The reader must infer that this is the creation path.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description's phrasing 'Store totals' is ambiguous and a reader could take it as a persistence operation, which pulls against the read-only annotation; it also says nothing about aggregation granularity (per-provider, per-day, cumulative) or what an empty range 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?

A single short sentence with no filler, and the most important information (that it returns totals, over a date range, for specific metrics) is front-loaded. It is efficient but slightly too terse to resolve the verb ambiguity.

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

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

With no output schema, the description usefully enumerates the metrics returned, which is the key missing structured information. It still omits the shape of the response (single object vs. breakdown by provider or day) and any mention of related detail tools, leaving an agent unsure what to expect back.

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 have format details plus default behavior documented inline, so the description need not repeat them. It correctly frames the parameters as a date range, but adds no semantics beyond that, so baseline 3 applies.

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

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

The description names the resource (totals) and enumerates the metrics returned (revenue, provider pay, bookings, ratings, referrals) over a date range, which lets an agent distinguish it from the list_* tools. However, the leading verb 'Store' is vague and does not clearly state that this is a read that returns aggregate figures rather than a write that persists them, and the name 'dashboard' alone conveys nothing.

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

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

There is no explicit guidance on when to use this tool versus siblings such as list_bookings, list_charges, or list_invoices, which could plausibly provide overlapping data. The implied use case (summary metrics rather than row-level records) has to be inferred entirely from the metric list.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description's contribution is enumerating the returned payload (price breakdown, provider pay, notes, service), which matters because there is no output schema — that is real added value beyond the 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?

One short clause with no waste, and the returned fields are front-loaded. It is a sentence fragment with no leading verb, which is slightly awkward but not costly.

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 full annotations and full schema coverage, the description covers the essential unknown — what comes back. Missing only minor items such as not-found behavior, which an agent can reasonably infer.

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

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

Schema description coverage is 100% and the single booking_id parameter is documented in-schema, including its provenance ('Booking id from list_bookings'). The description adds no additional meaning about the identifier, so the baseline 3 applies.

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

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

The phrase 'One booking with its price breakdown, provider pay, notes and service' clearly identifies a single-record retrieval and enumerates its payload, so it reads distinctly against list_bookings. The verb is only implied ('One booking' rather than 'Get one booking'), and no sibling is named explicitly, which keeps it short of a 5.

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

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

Usage is only implied: the agent can infer this is the detail-fetch for a known booking id versus the list tool. There is no explicit statement of when to prefer this over list_bookings, no prerequisite or exclusion, and nothing about behavior when the id does not exist.

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

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

Annotations already cover read-only, idempotent, closed-world safety, so the description is free to add value — and it does by disclosing the payload contents (contact details, addresses, booking counts, uncharged bookings), which matters because there is no output schema. It does not say what happens for an unknown customer_id, a minor gap.

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

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

A single compact sentence that front-loads the entity and immediately lists what comes back; no filler, no redundant restatement of the tool name.

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 getter with no output schema, the summary of returned fields is the essential missing piece and it is supplied. Only edge-case behavior (missing customer) is absent, which is a small omission.

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 and schema coverage is 100%, with the schema itself noting it comes from list_customers. The description adds no further meaning such as formatting or lookup failure behavior, 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?

Names the resource (one customer) and enumerates the returned data: contact details, addresses, booking counts, unpaid bookings. The 'one' distinguishes it from list_customers, though the verb ('get') is only implied by the title.

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?

No explicit statement of when to use this versus list_customers or get_booking; the single-vs-list distinction is only implied by the wording 'One customer'. An agent can infer usage but there are no stated conditions or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope of returned data and notes it works for teams too, which is useful context. However, it does not describe error handling, rate limits, or response format, so a 3 is appropriate given annotation coverage.

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

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

The description is a single, front-loaded sentence that lists the returned data efficiently. It is appropriately sized and wastes no words, though the fragment style could be slightly more structured with an explicit verb.

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

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

For a simple read tool with no output schema, the description fully states what data is returned and that it can represent a team. Combined with annotations and full schema coverage, it gives the agent enough to invoke the tool correctly. Missing pagination details for payment logs are covered by the schema.

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

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

Schema description coverage is 100%, with both parameters fully documented (provider_id origin and payment_logs_limit range/default). The description adds no parameter-specific information, so the baseline of 3 is correct when the schema does all the heavy lifting.

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

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

The description specifies a single provider or team and lists the data returned (contact, category, team members, reviews, payment logs). Combined with the name and title, an agent can tell it retrieves one entity, distinguishing it from list_providers. The verb is implicit rather than stated, keeping 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?

The description offers no explicit guidance on when to use this tool versus alternatives like list_providers. It implies usage through the required provider_id (schema notes it comes from list_providers) but the description itself provides no context, exclusions, or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not mention pagination behaviour, whether the cursor expires, or what the listing returns. The status words merely duplicate the schema enum.

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?

It is a single short sentence with no filler, which is good, but it spends its words re-listing status values already enumerated in the schema rather than front-loading the thing an agent needs: that this is a paginated filtered list endpoint.

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

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

For an 8-parameter paginated list tool with no output schema, the description leaves key things unstated: how paging works (limit/cursor), what the response contains, whether results are sorted, and how multiple filters combine. Annotations cover safety only, so the description should have carried more weight here.

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

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

Schema description coverage is 100%, with each of the 8 parameters documented in-schema including the status enum and default of 'upcoming'. The description contributes no additional meaning over that, so the baseline 3 applies.

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

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

The fragment "Bookings of the store" identifies the resource and scope, and the status list hints at what can be filtered. But there is no verb, and nothing distinguishes it from siblings like get_booking, list_charges, or list_customers. Purpose is inferable only because the tool name says '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?

No statement of when to use this versus alternatives such as get_booking (single booking), list_charges (payment records), or list_providers. No exclusions, prerequisites, or context for choosing among the overlapping status filters.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that results include payments and refunds; it does not disclose ordering, pagination behavior, or what is omitted, so it adds modest value beyond annotations.

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

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

The description is a single sentence with no filler, and the resource scope is front-loaded. It is concise, though it could be structured as a complete verb phrase to make the operation clearer.

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

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

For a five-parameter read-only list tool with no output schema, the description should clarify return content, pagination, or ordering at least minimally. It only hints at payments and refunds and leaves the agent to infer how the list is organized and how to traverse it.

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

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

Schema description coverage is 100%, and all five optional parameters are documented in the schema, including limit, cursor, search, start_date, and end_date. The description adds no additional filter syntax or parameter semantics beyond what the schema already provides.

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

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

The description identifies the resource as charged bookings with payments and refunds and ties it to the Charges page, but it never uses an explicit list/retrieve verb and does not distinguish this tool from siblings such as list_bookings, list_invoices, or refund_charge.

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

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

It gives no guidance on when to use this tool rather than list_bookings, list_invoices, or refund_charge, and it states no prerequisites, exclusions, or filtering intent beyond the schema itself.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds essentially nothing behavioral — notably it omits that results default to active customers only (inactive are excluded unless status is set) and that results are paginated. That default-filter behavior is a real gotcha an agent should be told about.

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

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

A single compact sentence with no waste, and the useful part (searchable fields) is placed after the resource identification. It is a sentence fragment lacking a verb, which costs it the top score but not much else.

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?

All four parameters are optional and fully documented in the schema, and rich annotations cover safety, so the description only needs light supplementation. It covers return contents and search fields but leaves out the active-by-default filtering and pagination expectations — the two things an agent is most likely to get wrong when calling it.

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

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

Schema description coverage is 100%, so limit, cursor, search and status are all documented in the schema; the baseline is 3. The description only reinforces the search parameter ('search by name, email or phone') and says nothing additional about status defaults or cursor semantics.

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 identifies the resource (store customers) and what comes back (email and phone), and adds search capability, but never states a verb such as 'list' or 'search' — that verb exists only in the title. The plural framing implies batch retrieval versus the sibling get_customer, but the distinction is never made explicit.

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

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

There is no statement of when to use this tool versus get_customer (single lookup) or create_customer, and no guidance on the expected workflow (e.g., page through with cursor, narrow with search). The mention of searching by name, email or phone implies one usage pattern but is phrased as a capability, not a routing rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description contributes the state constraint that results are only unbooked drafts, but says nothing about pagination behavior or the return shape.

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

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

A single short clause with no filler. It is appropriately sized for a simple query tool, though the fragment style means the action is never stated outright.

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-required-parameter list tool with full annotation coverage and no output schema, the description is minimally adequate. It omits pagination semantics and what a draft record contains, which an agent would want before paging or interpreting 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?

The schema documents all three parameters (limit, cursor, search) at 100% coverage, so the schema does the heavy lifting. The description adds no detail on filtering by customer, page size, or cursoring, so the baseline of 3 applies.

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

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

The description names the resource ('draft bookings and quotes') and adds a meaningful definitional constraint — they are 'not yet booked' — but it is a noun fragment with no verb, so the listing action comes only from the tool name. It does not distinguish itself from siblings like list_bookings or get_booking beyond the word '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?

There is no statement of when to use this tool versus list_bookings, get_booking, or send_quote, and no guidance on paging through results. The agent must infer the choice from the name alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered elsewhere. The description adds that results carry payment status, total and amount due — useful return context — but says nothing about ordering, pagination behavior, or the fact that searches span number/email/name/phone.

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 compact sentence whose most important information (scope: store vs. customer) is front-loaded, with no filler. It is a fragment rather than a full sentence, but nothing is wasted.

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

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

For a 7-param tool with no output schema, disclosing the returned fields helps, and defaults/ranges live in the schema. Still missing: result ordering, whether the cursor chain is stable, and any routing to related invoice tools, so an agent could call it correctly but not confidently.

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% with per-parameter descriptions and an enum, so the schema carries parameter meaning. The description only echoes the customer-scope dimension ('of one customer') and the returned fields; it adds no syntax, default, or interaction detail beyond the schema.

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

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

The description states the resource (invoices) and its scope: store-wide or for a single customer, plus the fields returned. That distinguishes it from data-focused siblings like list_charges or list_drafts, though it never names an alternative explicitly.

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

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

It implies this is a filtered listing tool but gives no when-to-use guidance or exclusions — nothing about when to reach for list_charges instead, or when resend_invoice is the appropriate follow-up. The agent must infer selection from the tool name alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the useful ordering guarantee (priority order) but says nothing about pagination behavior despite a cursor parameter, or about what fields a provider entry contains.

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

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

A single tight sentence with no filler, front-loading the resource and scope. It is perhaps too terse given the tool's filtering and pagination surface, but nothing is wasted.

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

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

With full schema coverage and rich annotations, the basics are covered, but there is no output schema and the description never indicates what a returned provider record looks like or how pagination/cursor results are shaped. Adequate but with a clear gap for a paginated list tool.

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

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

Schema description coverage is 100%, including enum semantics for type and status, so the schema carries the parameter burden. The description adds no parameter detail beyond the ordering note, which is the expected baseline when coverage is complete.

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 the resource and clarifies what a provider is (cleaners, technicians) plus that teams are included, and states the ordering (priority order). It does not explicitly contrast with siblings like get_provider, but the plural resource plus list semantics is unambiguous.

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

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

Usage is only implied by the name and the 'priority order' note; there is no statement of when to call this versus get_provider or how it relates to assign_provider. An agent can infer it is the enumeration step before assignment, but nothing is explicit.

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

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

Annotations already declare destructive=true, readOnly=false, idempotent=false, and openWorld=true. The description adds important context not in annotations: partial refunds are supported and the operation 'waits for the owner's approval,' which signals an approval flow that affects invocation behavior.

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

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

Two sentences with zero waste: purpose and full/partial scope are front-loaded, followed by the critical approval constraint. Every sentence earns its place.

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

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

For a mutation tool with complete schema coverage and annotations, the description covers purpose, partial capability, and the approval gate. It does not explain whether the call blocks until approval or returns a pending status, which is a minor gap given no output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents all five parameters including defaults and sources. The description adds only a high-level note about full/partial refunding, which relates to the 'amount' parameter but does not add syntax or usage detail beyond the schema.

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

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

The description states a specific verb ('Refund') and resource ('paid booking charge, extra, tip or fee'), plus scope ('in full or in part'). It is clearly distinguishable from siblings like list_charges or cancel_booking, though it does not explicitly name alternatives.

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 'Refund a paid booking charge' but there is no explicit when-to-use guidance, no exclusions, and no named alternative tools. The approval note is a behavioral prerequisite rather than usage guidance.

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

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

Annotations already declare this is a destructive, non-idempotent, open-world mutation. The description adds useful context that the change waits for owner approval, but it does not explain what happens to the original visit, whether the operation is asynchronous, or what the caller should expect after invoking it.

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 core operation and followed by an important approval caveat. There is no wasted text.

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

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

Given rich annotations and fully documented parameters, the description covers the main action and the owner-approval behavior. It is slightly incomplete about what the caller should expect after the approval wait, but no output schema exists and the core invocation guidance is present.

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

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

Schema description coverage is 100%, and the schema already documents booking_id, date, and notify clearly. The description reinforces the later-visit constraint on date but does not add 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 gives a specific verb and resource: postpone a visit of a recurring booking to a later visit date. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as cancel_booking or create_booking.

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

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

It implies the tool is for recurring bookings and only for moving a visit to a later date already in the schedule. However, it does not explicitly say when to use this instead of cancel_booking, create_booking, or adjust other booking details.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds a real behavioral fact not present in the annotations: the operation blocks on owner approval before delivery, which materially affects how an agent should sequence the call. It still omits what happens if approval is denied or the invoice is already paid.

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

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

Two short sentences, zero waste, with the action and channel options front-loaded and the approval caveat second.

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 mutating, approval-gated send tool with no output schema, the description covers the core action and the approval gate but leaves open the result shape (does it return pending?) and failure modes such as sending twice or sending on a paid invoice. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so every parameter including defaults is documented in the schema. The description's channel phrasing ('email, text or both') loosely reinforces the two booleans but adds no format or combination rules beyond the schema, matching the 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 and resource ('Send an invoice ... again') and enumerates channels, making clear this re-delivers an existing invoice rather than creating one. It does not explicitly distinguish itself from send_quote or list_invoices, so it stops short of a 5.

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

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

Provides one crucial usage condition ('Waits for the owner's approval') and implies the invoice must already exist ('again'), but gives no explicit when-to-use/when-not guidance versus siblings like send_quote or how to obtain the invoice_id.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds the important non-obvious behavioral detail that sending waits for the owner's approval, but it does not explain what happens after approval or rejection, nor the irreversibility implied by destructiveHint.

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

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

Two sentences, front-loaded with the core action and followed by the key approval condition. 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 5-parameter mutation tool with full schema descriptions and annotations, the description gives the essential purpose and approval precondition. A bit more on what happens after approval (e.g., whether sending is queued or immediate) would complete the picture.

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 is documented with a description and default. The description adds no parameter-level meaning beyond the schema baseline.

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

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

The description names a specific verb and resource ('Email a saved quote') and adds the outcome ('with a link to book it'). It is clear but does not explicitly differentiate from sibling actions like resend_invoice or list_drafts, so a 4 rather than a 5.

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

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

Usage is implied by 'saved quote' and the note that it waits for owner approval, which is a precondition. However, there is no explicit guidance on when to use this versus alternatives, nor any exclusions.

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