Partiful by Cotlet

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

With destructiveHint=true already present, the description still adds substantial context: approving triggers guest notifications by text or email, non-pending ids are rejected before any confirmation prompt, the call waits on the owner's approval by default (and that can be disabled per tool), and the return reports approved and still-waiting counts.

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

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

Front-loaded with the action and scope, and most sentences carry information. It loses a little to duplication between 'before the call waits for your approval' and the closing 'Waits for the owner's approval.'

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 the return values (approved count vs still-waiting count). For a three-parameter mutation with a human-in-the-loop gate, the key facts an agent needs are all 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%, so the baseline is 3, but the description adds validation semantics not in the schema: guest_ids that are not pending are refused, and 'all' acts as an alternative selector for the pending set rather than an additive filter.

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

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

Names a specific verb and resource ('Approve pending guests on a Guest Approval event') and anchors it to a familiar UI action ('as Approve on the host's guest list does'). An agent can distinguish it from invite_guests or check_in_guests from the description alone.

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

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

Gives the operative preconditions: the event must be a Guest Approval event, the caller must be a host, and ids must be pending or they're refused. It stops short of naming alternatives, so an agent must infer that invite_guests handles non-pending/new people.

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 (destructiveHint, idempotentHint=false, openWorldHint) by disclosing the human side effect (Partiful texts real guests by default), irreversibility ('cannot be undone here'), the already-canceled refusal, the host-only permission gate, and the approval/confirmation flow. These are exactly the consequences an agent must know before a destructive write.

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

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

Front-loaded correctly and dense with useful facts, but the guest-notification point is made twice ('Partiful notifies the guests' and 'By default Partiful texts the guests on the list with your message'), and the trailing confirmation/approval clauses are split across two sentences that say nearly the same thing. Trimming would improve it without losing information.

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

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

For a 3-parameter destructive tool with no output schema, the description covers everything an agent needs: what happens to the resource, who is affected, whether it can be reversed, failure conditions, permissions, and the confirmation gate. Nothing material is left to inference.

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 earns a step up by explaining the consequence of notify_guests=false (nobody is told) and implying the message accompanies the cancellation. It does not add format guidance for event_id or the 480-char message beyond what the schema already says.

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 ('Cancel an event') and immediately defines the semantic: the page stays up marked canceled, mirroring the in-page Cancel action. That framing distinguishes it from delete_event without needing to name the sibling, so an agent can pick correctly from the name plus description alone.

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

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

Gives real preconditions and branches: hosts only, an already-canceled event is refused, and notify_guests=false cancels silently. It stops short of explicitly naming delete_event as the alternative for removing an event entirely, so the routing guidance is strong 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?

Beyond annotations, the description discloses that guests receive no message, invalid guest IDs are refused, hosts only may use it, and it returns changed and total checked-in counts. These are important behavioral details for a mutating host-only operation.

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 short and front-loaded, but the first two sentences slightly repeat the check-in/undo action. The remaining sentences carry useful constraints and return information without excessive length.

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

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

With no output schema, the description usefully explains the return counts. It also covers host-only authorization, missing-guest refusal, notification behavior, and undo semantics, leaving little an agent needs to infer before calling it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining that undo reverses the check-in and that guest IDs not on the guest list are refused.

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: marking guests as checked in or undoing it. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as approve_guests.

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 establishes the check-in-at-the-door context and the undo variant, and notes that hosts only may use it. It does not explicitly name when to use a sibling tool instead, but the intended use case is unambiguous.

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 read-only, non-destructive, non-open-world behavior. The description adds useful context beyond that: authentication requirements, additional cost signal ('Free'), the status categories the response will contain, and the fact that a console link accompanies a recommended user step.

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

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

The definition is compact and front-loads the returned status information, with prerequisites stated briefly afterward. The status list is dense but each clause carries meaning, and there is little wasted text.

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

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

For a simple read-only lookup with one optional filter, full schema coverage, and annotations covering safety, the description supplies the important behavioral and return-value context an agent needs. Remaining gaps are minor, such as not stating whether omitting the filter returns all apps.

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

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

There is one optional parameter, and the schema fully documents it as 'Only this app, e.g. skool.' The description does not mention the filter parameter at all, but with 100% schema description coverage the baseline of 3 is appropriate.

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

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

The description states a specific resource (the user's workspace apps) and the exact status dimensions returned: access granted/requested, Cloud Browser account state, and next step with console link. It is clear what the tool reports, though it does not explicitly name or contrast with the sibling cotlet_request_apps tool.

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

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

The text gives prerequisites ('Free. Needs the user's Cotlet API key or sign-in.') but no when-to-use guidance or explicit alternatives. An agent must infer that this is the read-only counterpart to cotlet_request_apps, and there is no stated condition for selecting this tool over that sibling.

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

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

Annotations already flag destructiveness, open-world, and non-idempotency, but the description adds substantial context: it acts as the user, refuses payment and sign-in buttons, and details a per-minute credit cost plus a 3-minute idle session timeout. These behavioral traits exist nowhere in the structured fields.

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

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

Front-loads the core action, then layers caveats (refusals, cost, timeout). Every sentence carries useful information, though the pricing/session detail is dense and could be trimmed slightly.

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 states the return value (URL and title after click). Combined with refusal policy and session lifecycle, an agent has nearly everything needed to invoke correctly; only explicit sibling differentiation is missing.

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

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

Schema coverage is 100% and the element param is documented in the schema as its number in the element list. The description's phrasing mirrors that, adding little new meaning beyond the schema. Baseline 3 appropriate.

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

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

Specific verb (clicks) and resource (link, button, or element of current page), scoped by element number, and states the return value (URL and title). Clearly distinct from siblings like browser_press, browser_type, or browser_navigate.

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 use for clicking links/buttons and notes two refusal conditions (pay/buy buttons, sign-in/account pages). However, it doesn't explicitly contrast with siblings such as browser_press or browser_navigate, leaving the when-to-use-this-vs-alternatives inference to the agent.

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

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

Goes well beyond the annotations by disclosing what actually happens: cookies are preserved, the browser sleeps rather than being deleted, the per-minute charge stops, and the return value contains minutes and credits. The cost-stop detail is decision-relevant context no structured field provides.

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

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

Two sentences, no filler. The core action leads, and the state/cost consequences follow 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?

Absent an output schema, the description still describes the return payload (minutes and credits), and it covers lifecycle and billing effects. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing the description could add 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?

States a specific verb and resource ('Ends the session in the user's Partiful Cloud Browser'), which is unmistakably the counterpart of cotlet_browser_open. It does not explicitly name a sibling tool, but the operation is unambiguous.

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

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

Usage is only implied: an agent should call it when finished browsing. There is no explicit guidance on when to close versus leaving the session open, nor any warning about what becomes unavailable afterward (e.g., that the session cannot be resumed).

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

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

Annotations already declare readOnly/openWorld/idempotent=false/destructive=false, so the bar is lower; the description nevertheless adds real context: the final URL and title after redirects, the domain restriction ('Only Partiful pages open'), and a credit cost per started minute with a 3-minute idle timeout. Only sessions/preconditions are unstated.

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

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

Three short sentences, action first, then the domain constraint, then the cost/lifecycle caveat — each sentence carries distinct information with no repetition of the schema.

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

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

No output schema exists, so the description usefully says the return is the ending URL and title. Cost behavior is disclosed. Missing only the relationship to the sibling browser tools and whether a session must be opened first.

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?

Single parameter with 100% schema description coverage, so the baseline is 3. The description's 'public http or https address' duplicates the schema's format/description and adds only the domain restriction, not new syntax or semantics for the url argument.

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 (opens) and resource (a URL in the user's Partiful Cloud Browser) plus what it returns. It does not, however, distinguish itself from the sibling cotlet_browser_open, which an agent may reasonably confuse with 'navigate' — the one obvious clarity gap.

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 constraint 'Only Partiful pages open' implies when this tool is applicable, and the credit/session sentence implies operational context. But there is no explicit when-to-use versus cotlet_browser_open/cotlet_browser_click or prerequisite statement about whether a browser session must already exist.

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

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

Goes well beyond the annotations: discloses that a live user-visible session is created, that it is authenticated as the user, that every started minute costs credits, and that the session ends on close or 3 minutes after the last call. This billing and lifecycle context is exactly the kind of behavior an agent cannot infer from readOnlyHint/openWorldHint, and nothing contradicts those 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?

Identity is front-loaded in the first sentence, followed by routing, return value, and cost terms in four dense sentences with no filler. Each sentence carries information an agent needs before calling.

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 auth context, return value, session lifetime, and billing despite having no output schema, so an agent can call it correctly. The one substantive hole is the open-vs-navigate boundary with cotlet_browser_navigate, which the description never resolves.

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 one parameter at 100% schema coverage, the schema already defines `url` fully including the app-browser nuance. The description's 'Opens `url` when given' only hints that the parameter is optional (required: 0), adding little beyond the structured data.

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

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

States a specific verb and resource — wakes a real Partiful Cloud Browser signed in as the user — and says it opens `url` and returns the page URL and title. It distinguishes itself from the Partiful domain tools, but never contrasts with its closest sibling, cotlet_browser_navigate, which also goes to a URL.

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

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

'Use it for what the Partiful tools do not cover' gives a clear routing rule against the non-browser siblings, and the cost/auto-close note implies when to be economical. It offers no explicit when-not or alternative among the browser siblings (navigate, click, read), leaving that choice 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 context beyond the annotations: returns the URL and title after the press, Enter on account pages is refused, and sessions cost credits per started minute and end 3 minutes after the last call. These are real operational facts an agent needs that the destructive/openWorld annotations don't convey.

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

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

Front-loads the core action and effect examples, then tacks on return value and cost/session notes. Every sentence carries real information, though the cost/session sentence is slightly dense and could be trimmed.

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

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

Though there's no output schema, the description explains the return value (URL and title), the refusal rule, and session economics. For a single-param key-press tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and an enum restricts values, so the schema does the heavy lifting. The description still adds meaning by tying specific keys to effects (Tab moves to next field, Enter sends, Escape closes dialogs), which goes beyond the bare 'The key.' schema text.

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 (presses) and resource (one key on the current page in the Partiful Cloud Browser) and pins down the target (the focused element), which cleanly separates it from siblings like cotlet_browser_click and cotlet_browser_type.

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 examples (Tab to next field, Enter to send, Escape to close, arrows for suggestion lists) and a notable exclusion (Enter is refused on account pages). It doesn't explicitly route to cotlet_browser_type for text entry, but the key examples make the boundary clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavior the agent could not infer: a hard 20,000-character truncation, that both text and link list start near the current scroll position on long pages, that form field values and browser storage are deliberately omitted, per-started-minute credit cost, and the 3-minute idle session expiry. This is exactly the kind of cost/limitation disclosure that changes how an agent plans calls.

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

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

Four tight sentences, front-loaded with what is returned, then limits, then cost/lifecycle. Every sentence carries information an agent would otherwise have to discover by trial, and nothing is padded or redundant.

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

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

With no output schema, the description carries the return contract and does so well — content shape, size cap, truncation anchoring, and deliberately withheld data. It is slightly incomplete on failure modes (behavior with no open browser/session expired) and on how the returned indices map to click/type/select calls, which matters given the dense set of sibling browser 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?

Zero parameters and 100% schema coverage, so the baseline is 4; there is nothing for the description to disambiguate. The only cost is that the description doesn't tie the returned numbered link/button list to how it feeds sibling tools like cotlet_browser_click, which would be a small value-add.

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 verb and resource — returns the current page of the Partiful Cloud Browser — and specifies exactly what is returned: readable text up to 20,000 characters plus a numbered list of links, buttons and fields. That distinguishes it from a screenshot or navigate tool by content, though it never names the sibling it is contrasted with (e.g. cotlet_browser_screenshot).

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

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

Usage is implied: this is the tool to call to observe the page as text. The exclusions are about data ('field values, cookies and storage are never returned'), which nudges the agent toward other tools for those needs, but there is no explicit when-to-use-this-vs-screenshot/scroll/navigate guidance or precondition (e.g. must a session be open first).

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

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

Annotations already cover read-only/idempotent/non-destructive safety, but the description adds genuinely new behavioral facts: billing accrues per started minute and the session expires three minutes after the last call. It does not state the failure mode when no browser session is open, which is the one behavioral 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?

Return value is front-loaded in the first clause and the cost/session caveat follows immediately. Two sentences, no filler, though the 'boards, canvases and layouts' list is slightly vague padding.

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

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

For a zero-parameter tool with rich annotations and no output schema, the description supplies the return format (JPEG plus URL and title) and the session economics. The only omission is what happens when no browser is open, which is minor given the sibling set includes cotlet_browser_open.

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 the baseline is 4; there is nothing for the description to compensate for and it introduces no misleading parameter language.

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

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

States a specific verb+resource ('Returns a JPEG image of the visible part of the current page') and scopes it to visual content the page text does not show, which cleanly separates it from cotlet_browser_read without requiring the agent to open either 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 'boards, canvases and layouts that the page text does not show' implicitly tells the agent to prefer the text-reading sibling and reach for this only for visual content. It stops short of naming cotlet_browser_read or saying what to do when no browser session exists.

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 contradicts the idempotentHint=true annotation: scrolling down/up by `screens` viewport heights is relative movement, so repeating the same call from the new position produces a different scroll state. The description otherwise discloses useful behavior (mouse-wheel simulation, lazy loading, returned position, session cost), but the idempotency mismatch is a direct contradiction.

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 dense but front-loaded paragraph. Each sentence contributes: scrolling behavior, lazy-load effect, return values, and session cost model.

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?

Although there is no output schema, the description explains what is returned (URL, title, scroll position flags) and covers lazy loading and session cost. It is complete enough for an agent to call and interpret the tool correctly, aside from the annotation inconsistency.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description reinforces defaults and modes (screens default 0.8, down/up/top/bottom, element-in-view), but adds little semantic detail beyond the schema.

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

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

The description states a specific verb and resource (scroll the current page) and covers the supported modes: by screens, to top/bottom, or until an element is visible. It also distinguishes the follow-up action by noting that the next read will list newly loaded content.

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 clear usage context: scroll to load lazy content, reach an element, or go to page edges, and then use read to see loaded content. It does not explicitly name alternative browser tools or when not to use scrolling, so it falls short of a 5.

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

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

Goes well beyond the annotations: discloses the return value (URL and title after the selection), documents page-type refusals, and explains the session credit cost and the 3-minute idle expiry. This is exactly the operational context an agent needs before invoking a destructive, open-world browser action.

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 its locators, then appends return value and cost/session notes. All sentences carry information, though the credits/session tail is somewhat tangential to selecting an option.

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

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

No output schema exists, yet the description states what is returned, which page types fail, and session lifetime economics. 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%, so baseline is 3, but the description adds real meaning: the option may match the visible label as rendered 'or its value', which the schema's bare 'The option.' 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 (chooses) plus resource (an option of a drop-down list on the current page) and the two locators used to identify it. The 'drop-down list' scoping implicitly separates it from cotlet_browser_click/type, though no sibling is named explicitly.

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

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

Useful negative guidance: 'Card fields and account pages are refused', which tells the agent where this tool will not work. However, there is no positive statement of when to prefer this over cotlet_browser_click or cotlet_browser_type.

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 three things the agent cannot infer: the refusal policy for sensitive fields, the credit cost per started minute with a 3-minute idle expiry, and the post-action return of URL and title. That is exactly the operational context an agent needs before typing.

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

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

Three tight sentences, front-loaded with the action and addressing scheme, followed by restrictions and cost. No filler, though the billing/session sentence is only tangentially about typing and could be trimmed or moved to the family-level 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?

No output schema exists, and the description compensates by stating the return value (URL and title). Combined with the refusal policy and session-cost model, an agent has everything needed to invoke this correctly without further discovery.

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 text, submit and element are already documented. The description restates the same semantics (element = number in the element list, submit = presses Enter) without adding format, constraints, or edge-case behavior. Baseline 3 applies.

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

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

Names a specific verb (types text) and target (a field on the current page of the user's Partiful Cloud Browser), plus the addressing mechanism (element number in the page's element list). This clearly separates it from cotlet_browser_press, cotlet_browser_click, and cotlet_browser_select, which handle other input kinds.

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 a concrete when-not-to-use rule: password, card, one-time-code fields and sign-in pages are refused and left to the user. It also implies the element must come from a prior page read. It stops short of naming alternatives (upload, select, press) for the cases this tool doesn't cover.

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 mark this as destructive, non-idempotent and open-world, so the bar is lower; the description still adds concrete behavior: max 10 files at 20 MB each, the return payload (URL and title), and session economics — every started minute costs credits and the session ends 3 minutes after the last call. It omits what an existing file in the field does when overwritten, which is the main remaining question left by 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?

Three dense sentences with no filler; targeting, file formats, limits, return value and session cost each appear once and in a useful order. The cost warning is placed last where an agent will still see it before committing.

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

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

With no output schema, the description still states what comes back (URL and title), and it covers input formats, size/count caps, and the session lifecycle. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description genuinely adds meaning: it spells out both file-source shapes and the capacity limits that the schema only partly conveys via maxItems. The element parameter's meaning is already fully in the schema, so no further gain is possible there.

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 plus resource — puts files into a file field or the file picker an upload button opens — scoped to the current page of the user's Partiful Cloud Browser. The element-number targeting distinguishes it clearly from sibling tools like cotlet_upload_file (upload to Cotlet) 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?

Explains the two entry modes (an existing file field vs. a picker opened by an upload button) and gives the two accepted file sources, which is the key decision an agent faces. It does not explicitly name cotlet_upload_file as the prerequisite step for {"file_id"} or state when not to use this tool, so it stops short of full routing guidance.

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

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 readOnlyHint=false, destructiveHint=true and openWorldHint=true, but the description adds substantive context beyond them: the event is published immediately, nobody is invited or texted, the default visibility is private link-only, and the call returns the new event. The only gap is that it never mentions the destructive/permanence angle (whether the created page persists or how to undo) itself, relying on the annotation for that.

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 well front-loaded: the first sentence establishes the page, the second states the critical no-invites constraint. However, the invitation point is restated a third time ("Nobody is invited or texted; share url or call invite_guests"), which is redundant and costs a sentence that doesn't earn its place.

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

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

For an 11-parameter, non-idempotent mutation tool with no output schema, the description covers the essentials: what gets created, default visibility, the invitation side effect, the parameter conflict that causes refusal, and the return value ("Returns the new event"). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds cross-field semantics the schema only hints at: the guest_approval/max_guests mutual exclusion and refusal, the private-vs-public default, and the timezone interpretation of offset-less times. It doesn't cover the remaining params (questions, rsvp_deadline, location) but the schema documents those fully.

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 opens with a specific verb+resource ("Creates and publishes an event page hosted by this account") and explicitly positions the tool against its siblings by noting that nobody is invited until invite_guests is called. An agent can distinguish it from update_event, duplicate_event, and invite_guests 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?

It states explicit when-to-use context (create and publish a page, like Create on partiful.com with the default theme), what the next step is ("share url or call invite_guests"), and a hard when-not rule: "Guest Approval and a guest limit exclude each other, so a call with both is refused." Default behavior (private unless visibility is public) is also 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?

The annotations already mark this as destructive and non-idempotent, and the description adds substantial concrete behavior: page, guest list, photos, and messages are permanently gone; guests may be notified; only hosts can do this; calls require confirmation/owner approval. These details go well beyond the structured 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?

The description is front-loaded with the core destructive action and consequences, then covers the alternative, permissions, and confirmation behavior. Each sentence contributes distinct operational information for a high-stakes deletion tool.

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 with no output schema, the description provides the necessary consequences, alternative action, authorization constraints, and approval behavior. There are no material gaps for correct selection or invocation.

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

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

Schema description coverage is 100%, and the single parameter is already documented as “event_id from list_events.” The description does not add further syntax or selection guidance for event_id, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource, names the exact scope (“event you host for everyone, with its guest list”), and explicitly distinguishes this destructive action from cancel_event. An agent can identify what it does and which sibling preserves the page instead.

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 states the key condition for use versus the alternative: use this to permanently delete the event page and guest list, but use cancel_event to keep the page and notify guests. It also adds host-only authorization and confirmation/approval 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?

Goes well beyond the annotations by enumerating exactly what is copied (title, description, location, theme, questionnaire, RSVP settings) and what is not (guests, messages, RSVP deadline), notes 'Nobody is invited', states the auth constraint ('Hosts only'), and discloses the return value ('Returns the new event').

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

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

Front-loaded with the core action and scoped detail after, with no padding; however 'The copy has no guests yet' and 'no guests and no messages' restate the same fact in adjacent sentences.

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

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

For a write tool with no output schema, the definition covers copy semantics, permissions, non-invitation behavior, and the return value well; it is only missing an explicit statement of what the source event's state is after the call.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: the copy 'starts at start_at and keeps the original's length', clarifying that the end time is derived rather than supplied.

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 ('Copy an event ... to a new date') and immediately distinguishes it from create_event by equating it to the event-page 'Duplicate' action, so the agent knows it clones settings rather than starting fresh.

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: 'Hosts only' gives a permission precondition and the Duplicate analogy hints at the scenario, but no sibling (create_event, update_event) is named as an alternative, and no explicit when-not-to-use case is given.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the exact columns, that Status is Partiful's label (e.g. Approved on a Guest Approval event), that the text comes back inline rather than as a link, and that ids/emails/phones are excluded. Those are the details an agent needs before trusting the output.

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 key framing (CSV mirroring the Export CSV button) is front-loaded and the rest is dense with concrete facts. The second sentence slightly restates the first's equivalence to the button, a minor redundancy, but nothing is padded.

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

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

With no output schema, the description carries the return-value burden and does it fully: inline CSV text, row meaning, suggested filename, and excluded fields. Nothing an agent needs to call or interpret the result is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description restates status filtering ('for the chosen RSVP statuses') and clarifies the meaning of status labels as they appear in the output, but adds little syntax or semantics about the parameters themselves. Baseline 3 fits.

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 opens with a precise verb+resource+format: 'The guest list as CSV, the same file as the Export CSV button.' It also names the sibling it is not (list_guests for guest ids), so an agent can distinguish it without opening the schema.

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

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

It gives a clear routing rule away from the sibling: 'for guest ids use list_guests' and states the audience constraint ('Hosts only'). It implies filtering via the chosen RSVP statuses but never explicitly frames when to prefer this over list_guests for a plain listing, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: the payload is the host-facing page view, includes guests grouped by RSVP status and Questionnaire questions, and times are normalized to the event's time zone. The one gap is that it does not mention pagination or guest-list size limits for large events.

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?

Payload contents are front-loaded in the first sentence, followed by behavioral notes and then the access constraint, so the agent reads the most decision-relevant information first. Minor density in the field enumeration ('Guest Approval and waitlist settings') but no filler sentences.

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

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

With only one parameter and no output schema, the description carries the burden of describing what comes back, and it does so concretely: the event fields, guests per RSVP status, and Questionnaire questions. It also resolves the ambiguity of time zone and account reach, leaving nothing critical unstated before calling.

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, so the schema does the work. The description adds no format, prefix, or sourcing detail beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Full event ... Returns one event') and enumerates the fields returned (title, dates, location, RSVP deadline, guest limit, settings, link), which clearly separates it from a bare name/title. It never names a sibling such as list_events or list_guests, so the differentiation is implied through 'one event' rather than explicit.

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

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

Gives an explicit access boundary: 'Works for any event the account can open; the write tools need an event it hosts,' which tells the agent when the read is valid versus when a hosting relationship matters. It does not offer an explicit alternative path (e.g., 'use list_events to find an event_id'), so it stops short of full when/when-not 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?

Annotations already flag destructive/openWorld/non-idempotent, and the description adds substantial beyond-schema context: per-event limits (1,000 total, 500 email), canceled-event refusal, host-only auth, default confirmation with opt-out, owner-approval wait, and that invited_total reflects the post-call count.

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?

Dense but front-loaded: mechanism first, then limits and constraints. A few clauses (owner-approval, confirmation) stack at the end, but nearly every sentence carries operational value.

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, yet it explains the return (invited_total) and covers limits, auth, and refusal cases. An agent has enough to call correctly; only minor gaps like per-call failure semantics remain.

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 each parameter and its constraints (maxItems, maxLength, formats). The description reinforces email-vs-user_ids behavior and what message means, but adds only marginal syntax detail beyond structured fields; baseline 3 applies.

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

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

States a specific verb (Invite) and its resources (past guests, mutuals, email recipients), and clearly distinguishes itself from siblings like send_text_blast by naming the mechanisms and the list_past_guests source. An agent can identify its function without opening the schema.

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

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

Gives clear context: use for inviting via Partiful or email, sourced from list_past_guests (user_ids) or emails, and states no phone-number path exists. It lacks an explicit comparison to texting siblings like send_text_blast, but the when/mechanism guidance is solid.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world. The description adds genuine value beyond that: what fields come back (date, status, guest counts per RSVP status), that events are active or canceled, time-zone semantics (start/end in the event's time zone), and the sort order per filter. It does not cover pagination behavior or result-size expectations.

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?

Dense and front-loaded: scope first, then what is returned, then exclusions and ordering, then the event_id hand-off. Every sentence carries information, though the single paragraph is packed and could be broken for scannability.

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

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

With no output schema, the description carries the return-value burden and does so: fields returned, status values, guest counts, sort order and time-zone basis. Defaults and paging are covered by the fully described schema, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining the consequence of the `when` enum — upcoming sort soonest first, past sort most recent first — which the schema does not state. It says nothing extra about limit or cursor.

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

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

States a specific verb and resource (list the events this account hosts or cohosts) and scopes it tightly, explicitly excluding invited-only events. An agent can distinguish this from get_event (single event) or list_guests (attendees) without opening the schema.

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

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

Gives clear context for use — "as the Hosting tab of the home page lists them" — plus an explicit exclusion (invited-only events are left out) and a hand-off note to use event_id in other tools. It stops short of naming a specific alternative tool for single-event lookups, so no explicit when-not 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?

Annotations only declare it a safe read; the description adds the ordering ('oldest RSVP first'), the host-visibility scope, and non-obvious filter semantics ('going includes guests approved on a Guest Approval event'). That is real behavioral context beyond 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?

Purpose is front-loaded and nearly every clause carries information (return fields, ordering, auth, routing). The telegraphic, article-less fragments ('Hosts only.', 'guest_id goes to...') read slightly clipped but waste little.

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

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

With no output schema, the description carries the return-shape burden and does so explicitly: name, RSVP status, party size with plus-one names, check-in, RSVP note, questionnaire answers. Combined with annotations, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the floor; the description still adds value by clarifying what 'going' returns and where guest_id feeds downstream, plus noting that total counts filtered matches. It doesn't explain the cursor or checked_in interaction 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+resource (guest list of an event) and enumerates the returned fields, so an agent knows exactly what it gets. It doesn't distinguish itself from the sibling list_past_guests, which is the one ambiguity left.

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

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

Gives a clear access precondition ('Hosts only') and forwards to the right follow-up tools by naming approve_guests and check_in_guests for guest_id. It never says when to prefer list_past_guests instead, so it falls short of full when/when-not coverage.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, so the description correctly spends its budget on edge cases instead: a new account returns nobody, and shared_events or last_shared_event may be 0 or null when Partiful omits them. That null/empty disclosure is genuinely useful for an agent writing conditional logic. It stops short of describing ordering or pagination behavior, keeping it below a 5.

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

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

The core definition is front-loaded in the first sentence, and each subsequent sentence carries distinct information (return fields, exclusion param, search semantics, next step, degenerate cases). It is dense with several ideas packed per sentence, which slightly hurts scannability but wastes no 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?

With no output schema, the description usefully compensates by naming return fields (shared_events, last_shared_event, user_id) and their null behavior, and the cursor param is documented in the schema for pagination. Coverage is good for a read-only list tool; only ordering and total-count behavior are left unstated.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining what query matches, why not_on_event_id exists (mirrors the Invite list), and that the returned user_id is the value to hand to invite_guests. The 'user_id goes to invite_guests' phrasing is about a response field named like a parameter, which could momentarily confuse an agent looking for a user_id 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?

Opens with a concrete definition — 'People you can invite: your past guests and mutuals' — and pins the source: the people Partiful offers on an event's Invite screen. It distinguishes itself from the event-scoped guest-list siblings by stating 'there is no filter by one past event' and by naming invite_guests as the downstream consumer.

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 usage context: query does substring name matching, not_on_event_id excludes people already on an event, and results feed invite_guests. It also warns of a capability limit ('no filter by one past event'), which implicitly routes the agent elsewhere, though it never names the alternative tool (e.g. list_guests) to use for per-event filtering.

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 mark this destructive, non-idempotent, and open-world, and the description adds substantial context on top: delivery channels (SMS, email, app push, event feed), the 'cannot be taken back' irreversibility, the 480-character cap, the per-event blast quota, the recipient-count-at-send-time rule, and the fact that the response does not report remaining blasts.

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?

Information-dense and mostly front-loaded, but the 10-blasts-per-event cap is restated three separate times, and the closing notes about confirmation, the opt-out, and waiting for owner approval overlap each other. Tightening would cost nothing.

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 host-only broadcast with no output schema, the description covers irreversibility, channels, quotas, refusal conditions, confirmation behavior, and even what the response will not tell you. Nothing an agent needs before invoking is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters; the description only adds that statuses are evaluated at send time and that show_on_event_page defaults to the feed, which is marginal. It also references 'recipients and by_status' counters that do not exist as parameters, adding mild confusion 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?

States a specific verb and resource ('Text a message to guests') plus the scoping dimension ('by RSVP status'), which cleanly separates it from siblings like invite_guests or list_guests. An agent knows exactly what operation this performs without opening the schema.

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

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

Gives real preconditions: 'Hosts only', confirmation-by-default with an opt-out, the 10-blasts-per-event cap, and the refusal when a chosen status reaches nobody or when Invited exceeds 100 guests. It stops short of naming an alternative channel/tool, so it is strong context without explicit when-not/alternatives 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?

Goes well beyond the annotations: it discloses that omitted fields are preserved, that empty calls are rejected, that enabling Guest Approval wipes the guest limit and waitlist, that the first guest limit enables the waitlist, that new questions replace the questionnaire only for future RSVPs, and that the updated event is returned. These are exactly the destructive side effects an agent needs before calling a destructiveHint=true tool.

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

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

Front-loaded with the core action and the partial-update rule, then side effects, then return value and audience. Dense but every clause carries information; the enumerated field list is the one mildly redundant stretch given the schema already lists them.

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 destructive mutation with no output schema, the description covers update semantics, rejection cases, side effects, authorization scope, and the return value. A minor gap remains on whether changes notify guests and on ordering constraints (deadline vs. start_at), though the latter is handled in 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 coverage is 100%, so the baseline is 3; the description adds genuine cross-parameter semantics the schema only states in fragments – guest_approval/max_guests interaction and how questions replacement works over time. The plain field list (title, times, location, description, RSVP deadline) merely restates the schema, which keeps it from a 5.

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 ('Change the details or settings of an event you host') and immediately bounds the operation to a partial update of enumerated fields. It is clearly distinguishable from create_event, delete_event, and get_event without opening any sibling 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?

Provides a precondition ('Hosts only') and a usage rule ('Changes only the fields you give... a call with no field is refused'), plus a behavioral equivalence to the UI Edit page and settings panel. It stops short of naming sibling alternatives (e.g. use create_event for new events, cancel_event to cancel), so no explicit exclusion guidance.

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