Partiful by Cotlet

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

The annotations already disclose destructive, open-world, and non-idempotent behavior. The description adds a useful behavioral note that the tool 'waits for the owner's approval,' but it does not clarify whether this is blocking, asynchronous, or what happens on timeout/failure.

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 action and resource, with no wasted text. The key behavioral caveat is included compactly.

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 mutation with no output schema, the description is adequate but thin. It gives the core action and approval context but leaves failure behavior, permissions, and post-approval effects implicit.

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

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

Schema description coverage is 100%, so event_id, guest_ids, and the all flag are already well documented. The description adds context about pending guests but no additional parameter syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource: approve pending guests on a Guest Approval event. It is clear enough to distinguish this from invite/list/check-in siblings, though it does not explicitly name those 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?

The phrase 'pending guests on a Guest Approval event' implies the usage condition, but the description does not explicitly say when to use this instead of check_in_guests or how to handle non-pending guests.

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 destructiveness and non-idempotency, but the description adds useful behavior: Partiful notifies guests and the cancellation waits for owner approval. It omits whether the call blocks until approval and whether the cancellation is reversible, so it stops short of full disclosure.

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 core action stated first and the two relevant behavioral traits following. No filler.

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

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

For a destructive, approval-gated mutation with full schema coverage and no output schema, the description supplies the key workflow context. It could be more complete by explaining whether the call blocks until approval or what happens on rejection.

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 event_id, message, and notify_guests are already documented. The description does not add syntax or constraints beyond the schema; the statement that Partiful notifies guests is also slightly misleading because notify_guests can be set to false.

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?

It states a specific verb and resource ('Cancel an event') and is clearly a mutation. However, it does not distinguish this from the sibling delete_event, leaving the agent to infer the difference between canceling and deleting an event.

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 mention that it 'waits for the owner's approval' implies a specific workflow, but the description never states when to choose cancel_event over delete_event or what happens if approval is denied. Usage is implied rather than 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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description's useful addition is surfacing that the operation is reversible via the undo path, which softens the destructive framing. It stops short of stating batch limits (up to 500 guests), permission requirements, or partial-failure behavior for a mutation.

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

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

A single short sentence, front-loaded with the primary action and closed with the inverse. No filler; the only cost is that the extreme brevity leaves no room for operational detail that belongs elsewhere.

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

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

For a 3-parameter mutation with full schema documentation and a safety-carrying annotation set, the description is adequate but thin: it does not say that many guests can be checked in at once, what happens if some IDs are invalid, or that event_id must come from list_events. The structured fields cover most of the gap.

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

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

Schema coverage is 100%, so event_id, guest_ids and the undo flag are fully documented in structured fields, and the description's 'or undo it' confirms the meaning of the undo toggle at a glance. It adds nothing beyond the schema, but the baseline for full coverage is met comfortably.

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 (mark as checked in) and resource (guests) and adds the inverse operation ('undo it'), so the action is unambiguous. It does not, however, differentiate itself from the sibling approve_guests, which an agent could plausibly confuse with door check-in.

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 'at the door' hints at the physical check-in scenario but there is no explicit when-to-use/when-not guidance and no mention of the sibling approve_guests as the alternative for the approval workflow. The agent must infer the boundary 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 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, openWorldHint=true, and non-idempotent, so the mutation profile is covered. The description adds a valuable side-effect scope fact (no guests are invited on creation), but says nothing about what is returned, whether repeat calls create duplicates, or what permissions are needed.

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

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

Two short sentences, zero filler, with the resource statement front-loaded and the constraint second. 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 an 11-parameter creation tool with no output schema, the description omits what is returned — notably the event identifier needed to call invite_guests, which is the very next step it recommends. The schema covers inputs well, but the post-call picture is incomplete.

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 11 parameters are documented in-schema, including timezone defaults, max_guests waitlist behavior, and the guest_approval/max_guests interaction. The description contributes nothing beyond the schema, 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?

"New event page" identifies the resource and action, and naming invite_guests explicitly separates this from the guest-invitation sibling. It is slightly clipped (noun phrase rather than verb+resource), but an agent can tell what it makes and what it does not do.

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 one clear workflow hand-off (call invite_guests afterward), which is genuine usage context. But it never addresses when to use create_event versus duplicate_event, or what prerequisites/scope apply, so guidance is implied rather than complete.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds useful context beyond them by stating that the guest list is also deleted and that the action waits for owner approval, though it does not explain what happens after approval or whether the deletion is reversible.

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

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

Two short sentences with zero waste, front-loading the destructive scope and then the approval behavior. Every phrase contributes.

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

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

For a one-parameter destructive tool whose annotations already cover safety signals, the description is nearly complete. It could say more about the approval outcome or post-deletion behavior, but the core information an agent needs 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 coverage is 100% and the single event_id parameter is already documented as coming from list_events. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: deleting an event, scoped to events the caller hosts and including the guest list. It is clear, but it does not explicitly distinguish itself from the sibling tool cancel_event, so an agent may still need to infer the boundary.

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 for hosts deleting their own event and notes the owner-approval wait, but gives no explicit when-not guidance or mention of cancel_event as an alternative. The conditions for choosing deletion over cancellation are left implicit.

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

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

The annotations already declare destructiveHint=true and openWorldHint=true, so the description need not repeat safety metadata. It adds useful behavioral context beyond annotations by clarifying that the copy keeps event settings but has no guests yet.

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 action and immediately followed by the most important side-effect detail. There is no wasted text.

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

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

For a simple duplication tool with rich schema descriptions and annotations, the description covers the essential behavior, including that guests are not copied. It does not describe the return value, and no output schema exists, but that is a minor omission for this operation.

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

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

Schema description coverage is 100%, so the input schema already documents event_id, start_at, and title semantics fully. The description adds no parameter-specific meaning beyond what the schema provides, which is the baseline case for a 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?

The description states a specific verb and resource: copying an event with its settings to a new date. It is clear what the tool does, though it stops short of explicitly distinguishing itself from siblings like create_event or update_event.

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 'to a new date' implies when to use the tool, but there is no explicit guidance on when to choose duplicate_event over create_event or update_event, and no exclusions 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 carry readOnly, idempotent, and non-destructive. The description contributes the useful fact that output is byte-equivalent to the UI's Export CSV, but with no output schema it never explains how the CSV is delivered (inline text, attachment, link) — a real gap for an export 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?

A single front-loaded sentence with zero filler and no repetition of the schema. Brevity is appropriate, though it sits close to the edge of under-specification.

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

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

For a two-parameter read tool with full schema coverage the description is nearly sufficient, but the missing return-shape explanation (no output schema exists) and the absence of any sibling routing leave an agent to guess how to consume the result.

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

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

Schema description coverage is 100%, so both event_id and the statuses enum are fully documented in structured fields. The description adds no filtering semantics of its own, so baseline 3 applies.

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

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

States the resource (guest list) and the output form (CSV), which implicitly distinguishes it from list_guests — the JSON/paginated read. The 'same file as the Export CSV button' anchor makes the artifact concrete. Only weakness is that the verb is implied 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?

Usage is only implied: an agent can infer CSV is for file/deliverable output versus list_guests for data reads, but the description never names the alternative or states when to prefer each. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description contributes the payload shape (the set of returned fields), which is genuinely useful since no output schema exists, but says nothing about failure modes for an unknown or unauthorized event_id.

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

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

One compact sentence fragment, front-loaded with the key qualifier "Full event" and no filler. It is a noun phrase rather than a sentence, which is the main structural weakness.

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 field enumeration is exactly the missing piece an agent needs to know what a successful call yields. Only the error/not-found behavior and the distinction from list_events remain unaddressed.

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

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

Schema description coverage is 100%, and the single parameter's schema text already explains that the ID comes from list_events. The description adds no format, provenance, or fallback information 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?

"Full event: ..." signals a single-record detail fetch and enumerates exactly which fields come back, which implicitly separates it from the summary-oriented list_events sibling. It never states an explicit verb ("retrieve"/"fetch") or scope, so the purpose is inferable rather than declared.

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 call this versus list_events, list_guests, or update_event, and no prerequisites. The only routing hint lives in the schema ("event_id from list_events"), not in the description.

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

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

Annotations already declare destructive and openWorld, but the description adds genuinely new behavior: invites are queued pending the owner's approval rather than sent immediately. It still does not disclose the destructive consequence (e.g. whether invites can be revoked, notifications sent, or partial-failure behavior), which matters given destructiveHint=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?

Two short sentences with no waste; the audience/channel distinction is front-loaded and the approval caveat follows immediately.

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 open-world, destructive mutation with no output schema, the description covers who can be invited and the approval gate, which is the critical non-obvious fact. It omits what a call returns and what happens on partial or rejected invites, so it is close but not fully complete.

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

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

Schema coverage is 100%, so the schema documents all four parameters including the event_id source and user_ids source. The description only loosely maps its two channels to user_ids and emails and adds no format or limit detail, so it stays at the baseline for a fully-documented 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?

A specific verb (invite) plus resource (guests) with the two supported invite paths named: Partiful past guests/mutuals and email. It is distinguishable from approve_guests by the mention that invites wait for approval, though it never names that sibling directly.

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

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

It clearly states which channel fits which audience: Partiful for past guests and mutuals, email for anyone else. There is no explicit when-not-to-use guidance or mention that approve_guests is the follow-up step, so the selection logic is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds only the returned fields (date, status, guest counts) and does not disclose behavioral traits like pagination behavior or permission requirements beyond what the schema implies.

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, front-loaded sentence with zero wasted words that efficiently conveys the scope and returned fields.

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

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

For a simple read-only list tool with full schema coverage and rich annotations, the description is nearly complete. It could be slightly more explicit that it lists events (rather than just implying it) and mention pagination defaults, but those 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 clear descriptions for all three parameters (when, limit, cursor). The description adds no additional 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 (events), scope (you host), and included fields (date, status, guest counts), making the intent clear. However, it does not use the verb 'list' explicitly (only the title does), and there is no direct sibling that lists events, so differentiation is not needed but the purpose is slightly less sharp.

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

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

The description provides no explicit when-to-use guidance, no when-not-to-use conditions, and no mention of alternatives such as get_event for retrieving a single event. Usage is only implied by the phrase 'Events you host'.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds some value by disclosing what data is returned (RSVP status, check-in state, questionnaire answers), but it says nothing about pagination behavior or the cursor/limit contract that governs a list 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?

It is a single short fragment with zero padding, which is efficient. However, it is not a complete sentence and has no front-loaded verb, so it reads as a label rather than a usable instruction.

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

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

For a read-only list tool with full schema coverage, complete annotations and no output schema, the essentials an agent needs to call it are present: the resource, the required event_id implicitly, and the returned fields. Missing past/current differentiation is the main residual gap.

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

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

Schema description coverage is 100%, so limit, cursor, status, event_id and checked_in are all documented in the schema itself. The description's mention of RSVP status and check-in loosely signals the status and checked_in filters but adds no meaning beyond what the schema already provides; baseline 3 applies.

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

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

The fragment names the resource (guests of an event) and the fields carried back (RSVP status, check-in, questionnaire answers), so an agent can infer a read/list operation. But it never states a verb and gives no differentiation from siblings like list_past_guests or export_guest_list, which are the most likely confusions.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to or away from list_past_guests, export_guest_list, or approve_guests. An agent must infer from the name alone whether this is the right tool for current vs. past guests.

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 (readOnlyHint, idempotentHint, destructiveHint false, closed-world), so the description only needs to add data-scope context, and 'past guests and mutuals' does that. It says nothing about pagination behavior or what a result set looks like, which is a modest gap given the cursor parameter.

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 scope front-loaded. It reads as a fragment rather than a definition, which keeps it from a 5, but nothing should be cut.

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 four optional params, no output schema, and rich annotations, the definition is adequate but thin. It never addresses pagination via cursor or the exclusion behavior of not_on_event_id, both of which an agent would want framed at the description level.

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

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

Schema description coverage is 100% and each of the four parameters carries its own documentation, including the non-obvious not_on_event_id. The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

The description identifies the resource precisely: people you can invite, i.e. past guests plus mutuals. The scope addition ('and mutuals') goes beyond the tool name. It never says 'list' or gives a verb, and it does not distinguish itself from the sibling list_guests, so it falls short of a 5.

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

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

There is no explicit when-to-use guidance and no named alternative. 'People you can invite' hints at a pre-invite discovery flow, but the agent gets no instruction on choosing this over list_guests or moving on to invite_guests.

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 destructiveHint=true, openWorldHint=true and non-idempotent, but the description adds genuinely new behavior: a hard quota (10 per event) and an asynchronous gate (waits for owner's approval) that means the call does not fire immediately. That approval/rate-limit context is exactly what annotations cannot express. It still doesn't say what happens if the quota is exhausted or what the caller observes while pending.

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

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

Three short sentences, front-loaded with the core action, then the quota, then the approval gate. Every sentence carries information an agent needs and there is no filler.

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

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

For a non-idempotent, destructive broadcast with no output schema, the description supplies the critical operational facts (quota, human approval) and the recipient targeting. Only edge behavior — quota-exceeded errors and the post-approval outcome — is left unstated, which is a minor gap.

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

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

Schema coverage is 100%, so event_id, message, statuses and show_on_event_page are already documented, including the enum values. The description only echoes the status filtering ('by RSVP status') and adds nothing about message length limits or the show_on_event_page default. Baseline 3 for a fully documented 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 (text/send) plus resource (message to guests) and a scoping filter (RSVP status), which separates it from invite_guests and approve_guests. It doesn't explicitly name a sibling alternative, so it stops short of 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 makes the use case clear (broadcast texting segmented by RSVP status) and adds two decision-relevant constraints: the 10-blast-per-event cap and the owner approval requirement. It does not say when to prefer another channel or tool instead, so no exclusions are provided.

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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond that – it doesn't say whether omitted fields are left untouched (patch semantics), whether guests are notified, or that changes may be irreversible. No contradiction, but no added context either.

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 efficient sentence with zero waste and the ownership constraint front-loaded. It is slightly under-sized for an 11-parameter mutation tool, which costs a point against appropriateness of size.

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

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

For a destructive, non-idempotent tool taking 11 optional fields, the description never addresses the central ambiguity: whether unchanging fields are preserved or reset, and what happens to dependent settings. With no output schema and no explanation of the response, an agent has to guess at partial-update behavior.

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

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

Schema description coverage is 100%, so all 11 parameters including the interaction between guest_approval and max_guests are already documented in the schema. The description contributes no additional parameter meaning, which is the correct baseline when the schema does the work.

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 ("Change") and resource ("event"), plus a scope ("details or settings") and an ownership qualifier ("you host"). That distinguishes it from create_event, cancel_event, delete_event, and duplicate_event without opening any schema, though the field set itself is only described generically.

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 "an event you host" is an implied precondition that tells the agent when this tool is applicable versus the get_event/cancel_event siblings. However, there are no explicit when-not rules, no mention of duplicate_event as the alternative for copying, and no note about which of the mutually exclusive siblings to prefer.

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