Cotlet

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds two facts not in annotations — it is free and opens no browser session — which matter for cost and side-effect decisions. It does not describe output size or format beyond the content list.

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 purpose and content inventory lead, and the two operational constraints (call before the first step; free, no session) close it. The first sentence is a dense comma-list that takes a second pass to parse, but no sentence is wasted.

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

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

With no output schema, the description carries the burden of saying what comes back and does so by enumerating the guide's contents. Combined with the always-works fallback and the no-cost note, an agent has everything needed to decide to call it and what to expect.

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

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

Schema coverage is 100% and both parameters (app, task) are documented inline, so the baseline is 3. The description gestures at the app parameter ("which browser to use for this workspace", "the app's screens") but adds no format or usage detail beyond the schema's own examples.

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 (a per-app working guide for the Cloud Browser) and enumerates what it contains: browser choice, sign-in link, method, screens, menus, actions, notes, dedicated tools. An agent can tell this is documentation retrieval rather than a browser action, though it never names the browser_* siblings it is meant to precede.

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 trigger: "Call it before the first browser step in an app." Also covers the fallback case — an app outside Cotlet's catalog still returns the general method — so the agent knows a miss is not fatal. No explicit when-not or named alternative, which keeps it from 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?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Adds real behavior beyond the annotations: the tool answers with the page after the click (elements and text in view, same numbering), reports when nothing changed, and redirects new-tab links into the current tab. It also discloses a refusal policy for payment and sign-in targets. It does not say what the refusal looks like (error vs. message), which is the main remaining gap for a destructive, open-world 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 two targeting modes, then the post-click answer, then the safety constraints. The telegraphic style is dense but every clause carries information; a slightly clearer phrasing of 'with the same numbers' would help, but no sentence is waste.

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

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

With eight optional parameters and no output schema, the description covers the essentials: how to target, what modifiers exist, what comes back, and what is refused. It leaves dialog/dialog_text/app handling entirely to the schema and does not describe how a refusal is surfaced to the caller.

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 every parameter already carries its own explanation, so the schema does the heavy lifting. The description restates the element-vs-coordinates targeting and the double/right modifiers but adds no syntax or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (clicks) plus both targeting modes (element number or x/y pixel point) and names the modifiers (double, button: right). It is clearly distinguishable from siblings like cotlet_browser_hover, cotlet_browser_drag, cotlet_browser_press and cotlet_browser_select, which cover other interactions.

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 when-not: buttons that pay or buy, and sign-in/account pages, are refused, which warns the agent away from those targets before it calls. It also states that links meant for a new tab open in this one, so the agent knows not to follow up with tab management. It stops short of naming sibling alternatives (e.g. hover vs click, press vs click) explicitly.

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 give generic safety hints (non-read-only, non-destructive, idempotent); the description adds real behavioral detail beyond them — cookies persist, the session sleeps rather than being destroyed, per-minute billing stops, and the call returns minutes and credits. None of this contradicts 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?

One sentence, front-loaded with the action and timing, followed by the state/billing consequences and the return value. Every clause earns its place.

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

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

For a one-optional-parameter lifecycle tool with no output schema, the description covers timing, side effects on session state, billing impact, and what the call returns. 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 description coverage is 100% and the single `app` parameter is fully documented in the schema, so the description carries no burden here. It does not mention the optional app targeting at all, so baseline 3 applies.

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

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

"Ends the browser session" is a specific verb+resource, and the description scopes it to "when the task is done." It is clearly the counterpart to cotlet_browser_open, though it never names the sibling 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?

The trigger condition ("when the task is done") tells the agent exactly when to call it and implies it should not be called mid-task. No explicit when-not or named alternatives, but the context is unambiguous for a close operation.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety bar is partly covered. The description adds genuine behavioral context the annotations don't: the returned link expires in 15 minutes and text files are also returned as text. It does not explain why the operation is flagged destructive (a file is written to disk somewhere) or where that artifact lands, leaving a notable gap for a mutation-class tool.

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

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

A single sentence with zero filler, front-loaded on the verb and the two trigger modes. The colon-chain and semicolon packing make it denser than it needs to be, but no sentence is wasted.

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

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

With no output schema, the description correctly takes on the job of describing the return: file name, type, size, a 15-minute link, and text extraction for CSV/JSON/text. Missing are failure behavior when no download starts and any size or binary-handling limits, which matter for a broad open-world tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add a little meaning — it clarifies that `element` is specifically a download link or button, and that `url` is the page whose download should be started — but it says nothing about the `app` parameter the schema handles separately. Marginal value 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 names a specific verb ('Gets the file') and the precise trigger condition ('that clicking `element` ... or opening `url` starts'), which separates it from cotlet_browser_click and cotlet_browser_navigate. It also previews the payload (name, type, size, expiring link). It stops short of 5 only because the phrasing is elliptical ('answers its name, type, size'), forcing the agent to parse a compressed clause.

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 supplies clear context for selection: use this when a click or URL *starts a download* rather than producing a page, which implicitly routes the agent away from plain browser_click for that case. It gives no explicit exclusion or named alternative, and says nothing about what to do if the click does not actually trigger a download.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotent, so the safety profile is covered. The description adds real value beyond that by stating the post-action observation ("Answers the page after it: the elements and text in view, with the same numbers"), which tells the agent it gets a fresh numbered snapshot for follow-up steps. It says nothing about the dialog/dialog_text behavior or irreversibility of drag outcomes, keeping it from a 5.

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

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

Two short sentences, zero filler. The action and its endpoints come first, the return behavior second, and the illustrative examples are embedded rather than listed separately.

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

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

For a five-parameter tool with nested from/to objects and no output schema, the description covers the action, the endpoint duality, and the return snapshot, which is what an agent needs to chain steps. The omission of dialog handling is a minor gap since the schema documents those fields fully.

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

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

Schema description coverage is 100%, and each nested coordinate/element field, the app slug, and the dialog enum are documented in-schema. The description adds no semantics beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb and mechanics: "Drags from one element or point to another," and concretizes it with three recognizable scenarios (card between columns, piece on a board, slider handle). It is unmistakably distinct from cotlet_browser_click or cotlet_browser_hover by name and by the two-endpoint structure, though it does not explicitly name those siblings.

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

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

The example scenarios implicitly tell an agent when this tool is the right choice: drag-and-drop reordering, board moves, slider manipulation. There is no explicit "do not use this for X, use click instead" exclusion or precondition guidance, so it falls short of the 5 bar.

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

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

Beyond the annotations, the description discloses concrete sandbox limits (no requests, clicks, submissions, cookie or storage access) and the Cotlet-specific quirk that filled field values read as '[hidden by Cotlet].' It does not explicitly warn that arbitrary JS can still mutate page state, which sits in tension with the destructiveHint=true annotation, but it does not contradict it either.

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

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

Three compact sentences: purpose first, usage routing second, constraints and a concrete example last. Every clause carries information and nothing is redundant with the title.

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

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

With no output schema, the description correctly explains the return contract (JSON of the return value) and supplies a worked example. Minor gaps remain around execution limits or what happens on script errors, but for a two-parameter evaluation tool the definition is sufficient 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 the baseline is already high, and the description adds meaning by showing the expected shape of the script ('return [...document.querySelectorAll(...)].map(...)') and clarifying that it is a function body that returns. The optional app parameter is left entirely to the schema, which is adequate given its own detailed description.

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 and resource: runs a JavaScript function body on the page and returns the result as JSON. It also distinguishes the tool from its siblings by saying 'act with the other tools,' so an agent knows this is the extraction path rather than the click/fill path.

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 when to use this tool ('extract data the page holds — a table, a list, attributes') and when not to, routing actions to the other browser tools. The example of scraping h2 elements reinforces the intended usage pattern without ambiguity.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotency, and the description adds genuinely new behavior: it is non-atomic (stops at the first failing field) and reports which fields were filled, and it never submits. It does not explain why the operation is destructive (existing values being overwritten), which is the one relevant 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?

Four short sentences, front-loaded with the core action and value-type contract, followed by the important negative constraint (does not submit) and the return behavior. No redundant restatement of the schema or title.

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

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

With no output schema, the description correctly covers the return value ('the elements and text in view, with the same numbers'), which is exactly what an agent needs to chain a following step. Failure semantics and submission behavior are covered; only the destructive/overwrite consequence of filling fields is 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, but the description adds real meaning by mapping value types to widget kinds (text for text fields, option label for drop-downs, true/false for checkboxes, radios and switches) and by stating fields are processed 'in the order a person fills them'. The app and dialog parameters are left to their own schema descriptions.

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 first sentence gives a specific verb and resource ('Fills several fields in one step') and immediately differentiates itself from single-element siblings like cotlet_browser_type or cotlet_browser_select by emphasizing batching. It also enumerates which widget kinds are supported and what value type each expects.

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 a clear follow-up condition ('Does not send the form: click its button after'), which tells the agent how this tool relates to a click step. It does not explicitly say when to prefer this over repeated cotlet_browser_type/cotlet_browser_select calls, but the 'several fields in one step' framing makes the choice obvious.

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, openWorld), so the description is free to add what they don't: that matching spans the entire page including frames, and that hits come back as labelled elements with numbers and as text lines. That is real behavioral value beyond the structured fields, though it says nothing about ambiguity or multiple-match behavior.

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

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

Two sentences, front-loaded with the action and scope, then the routing hint. The colon-and-list construction after 'frames included' is slightly dense but every clause carries information.

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

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

There is no output schema, so the description takes on return-value explanation and does so adequately by describing elements, their numbers, and matching text lines. A minor gap remains: it never explains what the element numbers are for (presumably addressing cotlet_browser_click), which an agent would need to act on the results.

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

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

Schema coverage is 100%, so the schema already explains `text`, `kind`, and `app` in detail. The description reinforces the page-wide scope of `text` but adds no syntax, matching rules, or case-insensitivity nuance beyond what the schema states, so this sits at the baseline.

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

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

States a specific verb and resource ('Finds `text` on the whole current page, frames included') and goes further by sketching the result shape (elements with their numbers, plus matching text lines). It does not name a sibling explicitly, but the scope statement makes the operation 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?

'Use it instead of reading or scrolling a long page for one thing' names two concrete alternatives (cotlet_browser_read, cotlet_browser_scroll) and the condition that favors this tool. It stops short of stating when this tool is the wrong choice (e.g. when you already know the element's ref).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: it discloses that the tool answers with the post-hover page state – the elements and text in view, numbered consistently – which is important since no output schema exists. It omits details like whether hover state persists or whether menus may auto-dismiss.

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 action and target lead, the intent follows, and the return behavior is packed into a compact clause. Nothing is redundant with the title or 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 four-parameter, no-output-schema tool, the description supplies the essential missing piece – a sketch of the response ('the elements and text in view, with the same numbers'), which links it to the sibling read/step answers. What remains thin is failure behavior (element not found, coordinates out of view) and any timing caveat.

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

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

Schema description coverage is 100%, including the element-vs-x/y alternative and the app override rule, so the schema carries the parameter burden. The description only restates the either/or target ('an element or a point') without adding format, precedence, or fallback semantics beyond it. Baseline 3 applies.

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

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

States a specific verb and resource ('Rests the pointer on an element or a point') plus the intent ('to open a hover menu, a tooltip or a preview'), which makes the action unmistakable versus click or drag. It stops short of naming any sibling tool explicitly, so differentiation comes only from the verb's semantics.

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 purpose clause implies when to reach for it – to reveal content hidden behind hover menus, tooltips, or previews. There is no explicit when-not guidance (e.g. use cotlet_browser_click to activate, cotlet_browser_find to locate), so the agent must infer the boundary against 20 sibling browser tools.

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, openWorldHint=true, non-idempotent and non-destructive. The description adds that it returns the resulting page's visible elements and text 'with the same numbers', which is useful post-action context. It says nothing about wait/load semantics, failure on unreachable URLs, or how dialogs block navigation beyond what the schema already documents.

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

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

Two short sentences, front-loaded with the action and then the result. 'With the same numbers' is slightly cryptic out of context but is a compact, deliberate reference to element numbering.

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

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

For a five-parameter navigation tool with a fully documented schema and no output schema, the description covers the action, the alternative (history), the tab scope, and the returned page snapshot. 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 description coverage is 100%, so the schema already explains `app`, `url`, `dialog`, `dialog_text`, and `history`. The description only mirrors the `url`/`history` usage, adding no format, precedence, or conflict-resolution 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?

States a specific verb and resource: opens `url` in the current tab, or moves `history` back/forward. The 'current tab' scoping implicitly distinguishes it from cotlet_browser_open and cotlet_browser_tabs, though it never names them.

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

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

Implied guidance is present: pass `url` to navigate, use `history` instead for back/forward. There is no explicit when-to-use-this-vs-sibling statement (e.g. versus cotlet_browser_open or cotlet_browser_wait) and no exclusions.

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

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

Goes well beyond the annotations: it discloses the auth context (the user is already signed in), the side-effect on the user's tabs (URL goes to the site's existing tab, else a new one, so existing tabs survive), and what is returned ('the elements and text in view, with the same numbers'). The readOnlyHint=true is mildly at odds with launching a session and possibly a new tab, but since nothing is destroyed this is a nuance rather than a 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?

Three short sentences, front-loaded with the action and the 'Call it first' rule, then tab behavior, then the return value — no filler. The final phrase 'with the same numbers' is terse to the point of being cryptic unless the agent already knows the numbering convention from sibling tools.

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

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

With no output schema, the description correctly compensates by summarizing the returned page view (elements and text, shared numbering). It is nearly complete for a two-parameter session-start tool; only the opaque 'same numbers' reference and the absence of any failure/blocked-site note keep it from a 5.

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 and this is the baseline case. The description adds only tab-targeting behavior for `url` and says nothing extra about `app`, whose 'leave it out' guidance lives entirely in the schema.

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

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

States a specific verb and resource ('Starts the user's Cloud Browser ... and opens `url`') and pins down the operating environment ('a real Chrome on Cotlet, where the user is signed in'). The imperative 'Call it first' plus the tab-allocation rule separates it from siblings like cotlet_browser_navigate or cotlet_browser_tabs without requiring the agent to open those schemas.

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

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

Explicitly tells the agent it must be called first, which is the key sequencing rule for the whole browser tool family. It stops short of stating when NOT to use it (e.g., that cotlet_browser_navigate or cotlet_browser_tabs should be used once a session already exists), leaving that inference to the agent.

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

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

Annotations already flag destructiveHint=true, openWorldHint=true, and non-idempotency, so the safety profile is covered structurally. The description adds two genuinely new facts: the keystroke goes to the currently focused element, and the tool returns a post-action snapshot of elements and text, so no follow-up read is needed. It does not explain why the action is destructive (submitting forms, confirming dialogs, triggering shortcuts), which is the one behavior an agent most needs warned about.

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

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

Two sentences, front-loaded with the core action and then the return behavior; the key list earns its space because it doubles as usage guidance. The trailing phrase "with the same numbers" is slightly cryptic, but nothing is 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 five parameters at full schema coverage, rich annotations, and no output schema, the description covers the missing piece — what comes back after the press. It is complete enough to invoke correctly; only the destructive consequences of a keystroke are left unstated.

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

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

Schema description coverage is 100%, so every parameter including dialog, dialog_text, and repeat is already documented, which sets the baseline at 3. The description only adds a gloss — "one character (a site's shortcut)" — for the single-character case; it adds nothing about app, dialog, or repeat semantics.

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

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

"Presses a key on the focused element" names a specific verb and resource, and the key examples (Enter to send, Tab to next field, Escape to close a pop-up) make the effect concrete. It never names a sibling, so the boundary with cotlet_browser_type (text entry) or cotlet_browser_select (option choice) is left to be inferred.

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 supplies clear context for which key to choose in which situation, and "Answers the page after it" signals that a separate read step is unnecessary. It stops short of explicit alternatives or exclusions — nothing says to use cotlet_browser_type instead when the goal is entering a string.

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 open-world, so the safety profile is covered. The description adds real behavior beyond that: a 20,000-character truncation limit, a deterministic ordering with open dialogs first, and explicit exclusions (no field values, cookies, or storage) that tell the agent what it cannot learn from a read. It stops short of saying what happens after the 20,000-character cutoff or how to reach the remainder.

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, and the payload description is front-loaded before the usage and exclusion clauses. Every clause carries information an agent needs: content, cap, ordering, trigger, alternative, and limits.

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 has to carry the return shape and it does — text plus a numbered control list, with a size cap and ordering rule. Combined with the exclusion list and the zero-required-parameter call pattern, an agent has everything needed to invoke it and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3; the `app` parameter's fallback rule and the `element` semantics are already fully spelled out in the schema. The description only restates `element` with illustrative examples (dialog, form, list), which is a marginal gain rather than new meaning.

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 — reading the whole current page — and enumerates exactly what comes back: the page text plus a numbered list of links, buttons, fields and controls. The scoping sentence distinguishes it from the narrower `element` read, so an agent can tell the two apart 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 an explicit trigger ('on a new page or when a step's answer is not enough') and names the narrower alternative (`element` for a dialog, form, or list). It does not mention `cotlet_browser_find` or `cotlet_browser_screenshot`, which are the other natural substitutes when only a targeted lookup or a visual check is needed, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely non-structured behavior: the capture is viewport-limited ("visible part") and returns JPEG, and image coordinates can be reused as click/drag targets. It does not mention whether scrolling is needed for off-screen content, but the viewport framing implies 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?

Two short sentences, the output format is front-loaded, and every clause carries actionable information (what you get, when to use it, how to act on it). Nothing is redundant with 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 one-optional-parameter read-only tool with no output schema, the description covers format, scope, and intended next action, which is enough to invoke it correctly. A note about scrolling for content outside the viewport would close the remaining gap.

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

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

There is a single optional `app` parameter and schema description coverage is 100%, with the schema itself explaining the 'leave it out' default and the Cloud Browser exception. The description says nothing about the parameter, so it adds no meaning beyond the schema — the baseline 3 for high coverage applies.

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

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

The description names the concrete output ("A JPEG of the visible part of the page"), which tells an agent exactly what the tool produces, and it implicitly separates itself from cotlet_browser_read by covering content "the text does not show". It stops short of naming that sibling, so the differentiation is inferred 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?

It gives a clear use condition — visual artifacts such as boards, canvases, maps, charts and layout — and then describes the follow-up action an agent should take with the result (click or drag by image x/y). The missing piece is an explicit exclusion pointing to cotlet_browser_read when the content is textual.

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?

With no output schema, the sentence "Answers the page after it: the elements and text in view, with the same numbers" is genuinely valuable – it tells the agent that a scroll returns a fresh page snapshot with stable element numbering, so no follow-up read is needed. It also discloses that lazily loaded content will materialize. Minor tension: repeated `down`/`screens` calls move further, which sits awkwardly with idempotentHint=true, though this is an annotation nuance rather than a description 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?

Two dense sentences with the scroll modes front-loaded and the return behavior last, which matches reading order for a caller. The closing clause "with the same numbers" is terse to the point of being cryptic without context from sibling tools, costing a point.

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

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

For a five-parameter, zero-required tool with no output schema, this covers the mode space and the return payload adequately. Remaining gaps are minor: no statement about waiting for content to settle after scrolling, no indication of what happens at the end of a page, and no guidance on how `inside` and `element` interact when used together.

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 goes slightly further by expressing mode-parameter relationships in prose – `screens` is scoped to down/up, `element` switches to scroll-until-visible, and `inside` scopes the scroll to a panel or list. That helps an agent reason about which parameters combine, even though most individual meanings are already in the schema.

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

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

The description gives a concrete verb ("Scrolls with the mouse wheel") and then enumerates every mode: up/down by `screens`, to top/bottom, until an `element` is in view, or inside a panel/list. That enumeration makes it unmistakably the scrolling tool among siblings like cotlet_browser_find, cotlet_browser_read, and cotlet_browser_click, without needing to open 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?

"Content that loads on scroll appears" hints at the main use case (lazy/infinite-loaded content) and "until `element` is in view" implies a bring-off-screen-element-into-view scenario. However, it never explicitly says when to prefer this over cotlet_browser_find or cotlet_browser_read, and gives no exclusions or prerequisites, so 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?

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: it answers with the page's elements and text after acting, with numbering preserved. It does not explain what might be destroyed (e.g., a change/selection event that submits a form), which matters given destructiveHint=true.

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

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

Two short sentences with zero filler, front-loading the action and its accepted inputs before covering the fallback and the post-action result. Every clause carries information.

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

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

With five parameters, no output schema and rich annotations, the description covers the core action, the fallback path and the return payload (page read-back), while the app/dialog/dialog_text parameters are fully documented in the schema itself. Minor gap: it does not say what page change the selection triggers, relevant given the destructive flag.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: 'option' may be supplied as the visible label OR the underlying value (schema only says 'The option.'). 'element' semantics are already fully spelled out in the schema, so no further credit 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?

States a specific verb ('Chooses') and resource ('option' in drop-down 'element') and clarifies the accepted option formats, which is clearer than the generic title 'Choose from a list'. The 'home-made drop-down' sentence gestures at the click-based alternative but never names cotlet_browser_click as the sibling to use.

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 the native-select case directly and hints that non-native drop-downs are handled by clicking instead, which is useful conditional guidance. However, it never states explicitly whether that fallback is performed by this tool or by the agent using cotlet_browser_click, and there are no exclusions or preconditions.

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, openWorldHint=true and idempotentHint=false, so the bar is lower, and the description still adds real behavior: a hard cap of 8 open tabs, the side effect that switch redirects all later steps, and the hygiene rule to close only self-opened tabs. It does not say what happens when the cap is hit or whether closing a tab loses unsaved state, which are the remaining behavioral gaps.

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 resource is stated first and each remaining clause earns its place by describing one action or one constraint; nothing is redundant. The action clauses are packed into one long semicolon-chained sentence, which is dense but still parseable.

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 states what list returns (id, URL, title, which tab is shown) and discloses the 8-tab limit, so an agent can plan a tab workflow. It is slightly thin on return/error behavior for new, switch and close, but adequate for a 3-parameter 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 baseline is 3; the schema already explains tab, url and the action enum. The description does add the useful mapping of which parameter pairs with which action (`switch` with `tab`, `new` with `url`, `close` with `tab`) and confirms list as the default, but adds no format or validity 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 opens with a concrete resource ('the tabs of the user's web browser') and enumerates the four operations with their verbs (list, switch, new, close), each bound to its parameter. It fails to distinguish this tool from overlapping siblings such as cotlet_browser_open and cotlet_browser_close, which an agent could easily confuse with the `new` and `close` actions.

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 conveyed per-action (use switch to make later steps act on a tab, work in the tab of the site the task is about, close only tabs you opened), which is genuine when-to guidance. However, there is no explicit routing against the sibling tab/browser tools, so the choice between this tool's `new` and cotlet_browser_open 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?

Annotations already flag destructiveHint=true and openWorldHint=true, but the description earns credit beyond them by specifying the destruction semantics ("replacing what it held"), the post-action return shape ("answers the page after it: the elements and text in view, with the same numbers"), and a hard refusal policy for sensitive fields. It does not cover the slow-typing or dialog behavior, though the schema documents those, so it stops short of a 5.

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

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

Four short clauses, each load-bearing: action, overwrite, submit, alternative, return, refusal. The core action and the sibling routing are front-loaded, with no filler or restatement of the name.

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

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

With seven parameters and no output schema, the description covers the two things an agent cannot get elsewhere: what the tool returns (the page's elements and text, with the same numbers) and which fields it will refuse. Combined with the annotation safety profile, 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 description coverage is 100%, so every parameter including app, dialog, slowly and dialog_text is already documented in the schema. The description adds only marginal semantic framing for element (it is a number carried over from the prior answer) and submit, which the schema largely states itself. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ("Types `text` into field `element`") plus two modifiers that change behavior: overwriting existing content and Enter-on-submit. It also names the sibling that handles the multi-field case, so an agent can separate it from cotlet_browser_fill_form without opening 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?

"For several fields use fill_form" gives an explicit alternative with the condition that selects it, and the refusal clause ("Password, card and one-time code fields are refused: the user types them") is a concrete when-not rule that prevents a failed call. Little 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?

Beyond the annotations (destructive, openWorld, non-idempotent), the description adds concrete behavioral constraints — max 10 files, 20 MB each — and, importantly, states that the tool returns a page snapshot (elements and text in view with the same numbering). That return-behavior disclosure is valuable since there is no output schema.

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

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

Two compact sentences, front-loaded with the action and immediately followed by file format and limits, then the return shape. Some phrasing is terse to the point of being clunky ("Answers the page after it"), but nothing is wasted.

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

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

For a 3-parameter mutation tool with full annotation coverage and no output schema, the description covers the action, addressing scheme, size/count limits, and post-call return behavior. Only the prerequisite of how to source a file_id or element number is left implicit.

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

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

Schema coverage is 100%, so the schema already documents element, files, and the url/file_id alternatives; the description largely restates those formats and the limits. It adds little meaning beyond the structured fields, which matches the baseline 3.

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

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

The description gives a specific verb and resource — "Uploads/puts files" into a file field or upload button addressed by `element` — so the action is unambiguous. It does not explicitly contrast itself with the sibling 'cotlet_browser_upload' vs 'cotlet_upload_file' distinction, though the "element" framing implies the browser context.

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 through "element: the element's number from the last read or step answer," which situates it in the read-then-act browser workflow. There is no explicit guidance on when to use this versus cotlet_upload or how to obtain a file_id first, leaving the agent to infer prerequisites.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real context the annotations cannot: the default wait (5s), the cap (20s), and the fact that it reports whether the text appeared and then returns the page contents.

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 short and front-loaded with the core behavior, but the trailing sentence is telegraphic and hard to parse ('Answers the page after it: the elements and text in view, with the same numbers'). The default and cap are tucked into a parenthetical rather than stated cleanly.

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 disclose the return shape, and it does: a yes/no on the text plus the page's visible elements and text. Combined with the default/cap timing details, an agent has enough to call it correctly, though the return description is imprecise.

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 carries the parameter documentation and baseline 3 applies. The description does add the default of 5 seconds for `seconds`, which the schema does not state, but `app` is left entirely to 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 names a specific verb and resource: it waits until `text` appears on the page, or for `seconds`, and is aimed at slow-loading results. That is clearly distinct from the read/find/navigate siblings, though it does not call out an alternative by name.

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 explicit context for when to use it ('for results that load slowly') and describes the two modes (text-based wait vs. plain duration wait). It stops short of stating when *not* to use it or naming an alternative tool.

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

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

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

Adds substantial context beyond the annotations: reports promise nothing, so the agent must tell the user it was sent and never that something will be built or fixed, and must never include passwords or tokens. It also states an auth requirement (Cotlet API key or sign-in). Minor friction remains between 'a missing dedicated tool is not a problem to report' and the schema's missing_feature enum covering a missing tool step, which an agent may have to reconcile on its own.

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 and nearly waste-free, with each sentence carrying a distinct rule (what to report, what not to report, what to promise, what never to include, auth). The opening sentence runs long with an embedded list, which slightly slows the scan.

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

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

For a 7-parameter submission tool with no output schema, everything an agent needs is present: report scope, kind routing, PII exclusions, auth prerequisite, and the required user-facing framing. Return values need not be explained because no output schema exists and the tool's effect is a fire-and-forget submission.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: which content belongs in the report (the page, the step, what you saw, error text, call_id) and how kind selection maps to user-facing intent. That goes beyond the field-level descriptions rather than restating them.

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

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

Names a specific verb and target ('Sends a report to the Cotlet team') and immediately enumerates the three reportable situations: failed tool, wrong data, blocking error, un-doable browser step. It is clearly distinguishable from its siblings, none of which submit reports.

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 when-to-use cases and an explicit when-not-to-use case ('A missing dedicated tool is not a problem to report: do the task in the browser'), plus a routing rule that a user-requested feature goes as feature_request. Alternative actions are named rather than implied.

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

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

Annotations only tell us this is a non-destructive, non-open-world write; the description adds what happens beyond that: grants are granted for all apps at once, dedicated tools appear only after the user signs in via Cloud Browser, the call is free, and it requires the user's Cotlet API key or sign-in. That is substantive behavioral and prerequisite context an agent cannot get from 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?

Content is dense and front-loaded with the core action and its all-at-once scope. Sentences are colon-chained and pack multiple ideas each (cost, auth, sign-in, verification), so it reads more like a compressed spec than clean prose, but almost nothing is filler.

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

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

For a two-parameter mutation tool with no output schema, the description covers prerequisites (API key/sign-in), cost, side effects (grant-all), and the failure boundary (access does not guarantee a task works). It does not describe what the call returns, such as per-app grant status, which is the remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a meaningful detail beyond the schema: slugs must be "as listed at https://cotlet.dev/api/v1/apps," which tells the agent where valid values come from and prevents guessing. It says nothing about the optional use_case parameter, 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 ("Requests access to apps for the user's workspace") and anchors it to a console equivalent ("as Request access in the console"), plus the crucial scope detail that "every app is granted at once." It also implicitly separates itself from cotlet_apps (listing) and cotlet_app_guide (working in an app), so an agent can route without opening schemas.

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

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

Explicitly states when NOT to use it: "Not needed to work in an app: the user's AI works in any web app in their Web browser with cotlet_app_guide." It further warns that granted access does not imply a task will work and directs the agent to verify in the browser, which is a concrete alternative path.

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

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

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.