Google Discover by Cotlet

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

Annotations only cover safety (readOnly, idempotent, non-destructive, closed-world); the description adds substantial behavior beyond them: parallel reads from multiple home IPs in the target country, a ~70-second ceiling, higher credit cost, the meaning of seen_in and best_position, sort order (most-seen first), and the complete=false condition. That is exactly the operational detail an agent needs before committing to an expensive call.

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

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

Front-loaded with the outcome (what you get), then mechanism, then return-field semantics, then cost/latency warning. Dense but nearly every clause carries information; the trailing 'because it makes many' is mildly redundant with the earlier parallel-read explanation.

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 fully carries the return-value burden: it names the per-card fields (seen_in, best_position), the ordering, and the complete flag, and it discloses cost and latency for an expensive operation. Nothing an agent needs to decide or call 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 of 3 already applies, and the description adds real meaning: the cards count is a target for distinct cards that stops early when the pool runs dry, and country determines which home IP the feed is read from, shaping the stories returned. It does not add format details beyond what the schema already states.

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 (collect Discover cards) plus scope (up to 300 different cards in a country, with appearance counts). It implicitly contrasts with a single feed read ('One read of the Discover feed holds about 31 cards'), but never names the sibling get_discover_feed, so separation 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?

Clear context for when to pick this over a plain read: it reads many times in parallel until the requested number of distinct cards is reached or the pool is exhausted, and it warns that a call takes ~70 seconds and more credits. Missing an explicit 'use get_discover_feed instead when you only need one read' routing statement.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: "Free, no browser session" tells the agent this call is side-effect-free and cheap, which matters when deciding whether to consult it before every app task. It could go further on whether the returned guidance is cached or versioned.

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

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

The core action is front-loaded, but the first sentence is a long run-on list of contents that reads as a grab-bag rather than a structured summary. The two follow-up sentences are efficient and each earns its place. Trimming or breaking the list would improve 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 must convey what comes back, and it does: recommended browser, sign-in link, step-by-step method, screens, menus, actions, notes, and pointers to dedicated tools. For a read-only advisory tool with two optional parameters, that is close to complete; only the fallback behavior when `app` is absent 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 both `app` and `task` are already documented, including the default of Google Discover. The description mentions browser choice per workspace and the general-method fallback, but adds no guidance on how to phrase `task` or what happens when `app` is omitted. Baseline 3 applies when the schema carries the load.

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

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

The description names the resource (a guide for working in a web app via Cotlet's browser tools) and enumerates what it contains: browser choice, sign-in link, step-by-step method, screens/menus/actions, notes, and dedicated tools. It is clearly distinguishable from the browser action siblings, which perform operations rather than explain them. The phrasing is somewhat run-on, but the purpose 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?

"Call it before the first browser step in an app" gives an explicit trigger point in the workflow, and "Works for any web app; one outside Cotlet's catalog gets the general method" sets expectations for unlisted apps. It does not explicitly name a sibling alternative or say what to do if the guide was already consulted, keeping it short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description only has to add context, and it does: no cost ('Free') and an authentication requirement (API key or sign-in). It also discloses the shape of the result content (per-app connection state plus the one remedial step and console link), which is meaningful beyond the annotations.

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

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

It is a single sentence plus two short fragments, so nothing is truly wasted, but the main sentence is heavily nested with parentheticals and a colon-list, making it harder to parse than necessary. The cost and auth facts land at the end rather than being surfaced as a distinct, scannable clause.

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 must convey what comes back, and it does — per-app status, the one required user action, and a console link. Cost and credential requirements are also covered. The only omission is any relationship to the sibling cotlet_app_guide or to the cotlet_browser_* tools that would act on the reported state.

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 optional 'app' filter is documented in the schema with an example ('skool'), so the schema carries the load. The description never mentions the filtering capability at all, which is a missed opportunity but not a semantic gap given full coverage. Baseline 3 applies.

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

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

The description names the resource (the workspace's apps) and states exactly what is returned per app: the Cloud Browser account state and the single next step with a console link. The three enumerated states (connected, signed out, signed in but not connected) make the scope concrete. It does not, however, distinguish itself from the sibling cotlet_app_guide, which an agent could easily confuse with this list.

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

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

There is no explicit when-to-use statement and no routing to or away from cotlet_app_guide or the browser tools. The only usage-adjacent content is the prerequisite 'Needs the user's Cotlet API key or sign-in' and the cost note 'Free', which tells the agent how to call it but not when to prefer it over alternatives.

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

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

Annotations already declare destructive, non-idempotent, open-world behavior, so the bar is lower; the description still adds real value by explaining the post-click return payload (elements and text in view, same numbering), the no-change signal, and the refusal policy for payment and auth surfaces. It does not cover what happens when an element is missing or off-screen, or how dialogs are surfaced.

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 target, then modifiers, then return behavior, then safety refusals — a sensible priority order with no filler. The telegraphic style ('Answers the page after it') is compact but slightly oblique.

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 optional parameters, no output schema and destructive annotations, the description does the heavy lifting on return shape and edge cases (new tabs, unchanged page, refused clicks). Minor gaps remain around element resolution failures and dialog interception, which the schema covers only partially.

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 the undocumented-in-description `dialog` and `dialog_text` is already explained. The description adds only a light framing of element-vs-coordinate mutual exclusivity and the double/right-click shortcuts, which largely restate 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 (clicks) plus the exact targets (element number or x/y point) and the modifier variants (double, button: right). It is unmistakably distinct from siblings like cotlet_browser_hover, cotlet_browser_drag, cotlet_browser_press and cotlet_browser_select.

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

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

Gives clear usage context plus an explicit when-not: pay/buy buttons and sign-in/account pages are refused, and new-tab links are redirected into the current tab. It does not name alternative tools (e.g. hover vs click), 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?

Goes well beyond the annotations: it discloses that cookies are preserved and the browser 'sleeps' (state is not destroyed, consistent with destructiveHint=false), that the per-minute billing stops, and what the response reports. Cost and state-retention details are exactly the operational context annotations cannot 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?

A single compact sentence with the action front-loaded, followed by the state and billing consequences and the return value. No redundant restatement of 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?

With no parameters, no output schema, and simple semantics, the description covers everything an agent needs: the trigger, the state outcome, the billing effect, and the shape of the response (minutes and credits). Nothing material 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?

There are zero parameters, so there is nothing for the description to disambiguate; the baseline applies. It correctly implies no inputs are needed to close the session.

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 browser session') and names the triggering condition ('when the task is done'), which cleanly separates it from the sibling cotlet_browser_open and the other browser_* action tools.

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

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

Gives a clear usage condition ('when the task is done'), which is enough to select it over the browser_* interaction tools. It does not explicitly say when NOT to close (e.g. mid-workflow with pending state) or name cotlet_browser_open as the counterpart, so it falls 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 declare openWorld, non-idempotent and destructive, so the bar is lower; the description still adds real behavioral facts the annotations do not carry, namely that the returned link is valid only 15 minutes and that CSV/JSON/other text files additionally come back as text. It does not explain why a download is flagged destructive or what happens to previously returned links/files, so it stops short of fully closing the gap.

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

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

A single dense sentence, front-loaded with the action and then the result payload; nothing is redundant. The phrasing ('answers its name, type, size and a link valid 15 minutes') is slightly compressed and grammatically loose, which costs a point on readability.

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 burden of describing the return payload (name, type, size, 15-minute link, text body for text formats), which is the key thing an agent needs. Gaps remain around size limits, binary handling, and whether `element` and `url` are mutually exclusive, but nothing essential to calling it is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds only modest meaning, clarifying that `element` refers to a download link or button and that `url` is opened to start the download, without expanding on the element numbering or exclusivity of the two inputs.

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

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

The description names a specific verb and resource ('Gets the file that clicking element ... or opening url starts') and enumerates what is returned (name, type, size, expiring link, text for text formats). It is clearly the download counterpart to cotlet_browser_upload and distinct from click/navigate, though it never names a 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?

Usage is implied by describing the triggering action: use it when a click on a download link/button or opening a URL starts a download. There is no explicit when-not guidance, no mention of preferring cotlet_browser_click or cotlet_browser_read when no download is triggered, and no prerequisites stated.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the description's job is to add context, and it does: "Answers the page after it: the elements and text in view, with the same numbers" tells the agent the call returns a fresh page read with stable element numbering, which prevents a redundant cotlet_browser_read follow-up. It does not disclose drag mechanics such as press-move-release timing, whether it waits for animations, or what happens if the drop misses a target, so it is valuable but not complete.

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 its accepted endpoint forms, then the return behavior. The colon-list of examples does real disambiguating work rather than padding, and there is no redundant restatement of the title or 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 no output schema, the description correctly covers the return value (elements and text in view with matching numbers), and the destructive/open-world annotations cover risk. For a nested-object, drag-and-drop tool the remaining gaps are edge behavior (invalid drop targets, drag during navigation, whether the page read reflects post-animation state), which are meaningful but secondary.

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 per-field notes distinguishing element numbers from screenshot pixels and documenting the dialog/dialog_text enum, so the schema carries the parameter burden and baseline 3 applies. The description reinforces that "from" and "to" each accept an element or a point, but adds no syntax, format, or interaction detail beyond what the schema already states.

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?

"Drags from one element or point to another" names a specific verb and both endpoint forms, and the three examples (card between columns, board piece, slider handle) make the operation concrete. Against siblings like cotlet_browser_click, cotlet_browser_hover and cotlet_browser_press, the verb itself carves out a distinct action, so an agent can select 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?

The example scenarios (reordering a card, moving a board piece, sliding a handle) give a clear sense of the situations this tool is for, which is real usage context rather than a bare restatement. It stops short of explicit exclusions or pointing at alternatives such as cotlet_browser_click for a simple press, so it lands at clear-context-without-routing rather than full when/when-not guidance.

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

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

Adds substantial behavior beyond the annotations: sandbox limits (no requests, clicks, submits, cookie or storage access) and the [hidden by Cotlet] redaction on filled fields, which an agent would otherwise only discover by failing. It does not address the destructiveHint=true / readOnlyHint=false profile, i.e. what happens if the script mutates page state, leaving a mild tension with the 'extract, don't act' framing, though nothing is outright contradicted.

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 capability, then the use case, then the hard limits, then a one-line example — no filler sentences. The 20000-character limit and other mechanical details are correctly left to 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?

With no output schema, the description carries the return contract and does so adequately by declaring JSON-serialized results. It omits failure behavior such as timeouts, thrown exceptions, or oversized return values, which matter for an arbitrary-script tool, so it falls just short of fully complete.

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

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

Schema coverage is 100% and already documents the single 'script' parameter, so the baseline is 3. The description earns an extra point by showing a concrete function-body example and clarifying the return path ('answers what it returns, as JSON'), which the terse schema line 'A function body that returns' does not convey.

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

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

States a specific verb and resource (runs a JavaScript function body on the page) plus the return contract (JSON), and distinguishes itself from the action-oriented siblings by saying 'act with the other tools.' An agent can tell this apart from cotlet_browser_read or cotlet_browser_click without opening any schema.

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

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

Gives an explicit when-to-use case ('extract data the page holds (a table, a list, attributes)') and routes state-changing work to other tools. It stops short of naming the closest alternatives, e.g. when cotlet_browser_read or cotlet_browser_find suffices, which would remove the remaining ambiguity about choosing evaluation over simpler extraction 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 declare a destructive, non-idempotent, open-world write, and the description adds new behavior: it stops at the first failing field, names the fields already filled (partial-state semantics critical for a destructive tool), and never submits. It stops short of explaining why it is flagged destructive or what side effects a fill can trigger, such as conditional fields appearing.

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

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

Four tight sentences, front-loaded with what the tool does before the failure and submission caveats. The closing line ('Answers the page after it: the elements and text in view, with the same numbers') is awkwardly worded but still conveys the return shape and element-number continuity.

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 value as a page read with contiguous element numbers and covers the critical submit/no-submit distinction. The gap is risk context: nothing tells the agent a fill can irreversibly alter page state or which forms are inappropriate to auto-fill.

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 the baseline is 3. The description adds useful mapping semantics — text fields take text, drop-downs an option label, checkboxes/radios/switches true or false — slightly beyond the schema's terser 'Text, option, or true/false', but dialog and dialog_text are 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?

States a specific verb and resource ('Fills several fields in one step') and enumerates the widget types handled. It does not name the sibling tools it supersedes (cotlet_browser_type, cotlet_browser_select), so differentiation is inferred from 'several fields in one step' rather than stated.

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

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

The tail gives real routing guidance: 'Does not send the form: click its button after', pointing the agent to cotlet_browser_click for submission. It implies batch filling replaces per-field typing but never states when a single-field sibling is preferable or what happens with a stale element number.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: matching spans iframes ('frames included') and results include element numbers plus each matching text line, which is what an agent needs to decide whether this beats a full read.

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, zero redundancy, front-loaded with the core action before the routing advice. Every clause carries information an agent would otherwise have to infer.

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 sketches the return shape (element numbers and matched text lines) and discloses cross-frame scope. What is missing is minor: behavior on zero matches, result caps, or whether hidden elements are included.

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

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

Schema coverage is 100%, with `text` documented as 'Words to look for, any case' and `kind` documented with an enum and default, so the baseline is 3. The description adds a little framing about matching against labels and text lines, but does not explain the `kind` filter's effect on results, so it does not exceed the schema meaningfully.

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 scope: finds `text` across the whole current page, 'frames included', and describes both what is matched (element labels and text lines) and what is returned (element numbers). This is clearly distinct from cotlet_browser_read and cotlet_browser_scroll, which it implicitly contrasts with.

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

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

Gives a concrete usage rule: 'Use it instead of reading or scrolling a long page for one thing,' which tells the agent when this tool beats its closest siblings. It stops short of naming the sibling tools directly or stating when-not to use it (e.g., for structural exploration), so it 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 cover read-only, idempotent, open-world and non-destructive, so the bar is lower; the description still adds real value by disclosing that the call returns the page state afterward ('the elements and text in view, with the same numbers'), which is important since there is no output schema. It does not explain what happens if no target is supplied or whether the pointer moves away.

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

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

Two tight sentences with the action first and the return behavior second. The phrase 'with the same numbers' is slightly cryptic but refers back to element numbering, so 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?

For a zero-required-parameter, non-destructive hover tool this is mostly adequate, and the absence of an output schema is partly compensated by the return-value sentence. Gaps remain: no default targeting behavior when no argument is given, and only a vague sketch of what the returned page answer contains.

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, and the description adds the element-or-point framing that tells the agent the three parameters form two mutually exclusive targeting modes. It does not address defaults or what happens when all three are omitted, which the schema also leaves open.

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 target: rests the pointer on an element or a point, and names concrete outcomes (hover menu, tooltip, preview). That is far more informative than the title 'Point at the page' and distinguishes it from cotlet_browser_click by implication (hover, not activate), 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?

Saying it opens hover menus, tooltips or previews implies when to reach for it, but there is no explicit when-not guidance and no pointer to cotlet_browser_click for actual activation. The agent must infer the click-vs-hover boundary itself.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds behavior the annotations do not: that the step returns the resulting page state (elements and text in view). It omits whether navigation blocks on load, what happens on timeout or failed load, and what the 'same numbers' refer to, leaving some 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?

Two short sentences with the primary action front-loaded and no filler. The closing clause 'with the same numbers' is cryptic and costs clarity rather than words, which keeps it just below top marks.

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

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

With no output schema, the description does carry the burden of explaining the return value, and it does so only vaguely ('the elements and text in view, with the same numbers') without defining the numbering scheme or error behavior. For an open-world navigation tool that can trigger native dialogs, more on failure modes and load semantics would be needed for full completeness.

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 `url`, `dialog`, `history`, and `dialog_text` are already fully documented, including enum values and dialog defaults. The description restates only `url` and `history` and adds nothing about `dialog`/`dialog_text` semantics, so it does not exceed 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 ('Opens `url` in the current tab') plus the alternate mode ('goes `history` back or forward'), which is clearly navigation rather than the sibling `cotlet_browser_open`. The 'current tab' phrasing implicitly separates it from opening a new browser context, but no sibling is named explicitly, so an agent must infer the distinction.

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

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

Usage is implied by the mechanics: supply `url` to navigate, `history` to move within the session. There is no explicit guidance on when to prefer `cotlet_browser_open` (new tab/session) versus this tool, nor when to follow a navigation with `cotlet_browser_read` instead of relying on the returned snapshot.

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: the session is a real Chrome authenticated as the user (auth/session implications the hints do not convey), navigation is restricted to Google Discover pages despite openWorldHint, and it returns the visible elements and text using the same numbering as the other browser tools. That return-shape note matters because 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?

Compact and front-loaded with the action, with the sequencing rule immediately after. The phrase 'with the same numbers' is slightly cryptic and only resolves once the agent has seen the sibling browser tools, which costs a bit of standalone clarity.

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

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

For a one-parameter tool with no output schema, the description covers the action, the ordering, the scope restriction, the authentication context, and the shape of the response. 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%, so the baseline is 3, but the description adds a real constraint the schema lacks: only Google Discover pages will open, which qualifies the schema's generic 'public http or https address' example.

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: it starts the user's Google Discover Cloud Browser (a real Chrome signed in as the user) and opens `url`. It also distinguishes itself from the surrounding browser tools by saying it must be called first and is for what the Google Discover tools do not cover.

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 ordering ('Call it first'), an explicit scope limit ('Only Google Discover pages open'), and an explicit fallback rule ('use it for what the Google Discover tools do not cover'). An agent can decide between this, cotlet_browser_navigate, and the Discover card tools without opening schemas.

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, readOnlyHint=false and non-idempotence, so the safety profile is covered. The description adds genuinely non-structured behavior: the key goes to whatever element currently has focus, and the call returns the page state afterward ("the elements and text in view, with the same numbers"), which tells the agent it can chain a read directly after the press. It does not warn that a press may submit data irreversibly, but the annotations carry 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 tight sentences: the first states the action and its concrete uses, the second states the result. Nothing is wasted. "With the same numbers" is slightly opaque to an agent that has not read the sibling read/find tools, but it is a useful cross-reference rather than 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?

There is no output schema, and the description compensates by stating what comes back (visible elements and text, same numbering). Dialog handling and repeat limits live in the fully documented schema, and destructive/open-world behavior is carried by annotations. An agent has everything needed to call this 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 would be 3; the description exceeds it by mapping key choices to intent (Enter sends, Tab advances focus, Escape closes, arrows navigate lists/sliders, a single character triggers a shortcut), which is meaning beyond the enum listing. The dialog, dialog_text and repeat parameters are left entirely to the schema, which limits it to a 4.

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 ("presses a key on the focused element") and enumerates concrete intents (Enter to send, Tab to the next field, Escape to close a pop-up, arrows in a list or slider, single-character shortcuts), so the agent knows exactly what the tool does. It never names a sibling like cotlet_browser_type or cotlet_browser_click, so the boundary with typing text versus pressing discrete keys is left to inference.

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?

Several clear when-to-use contexts are supplied — submitting a form, moving focus, dismissing a pop-up, stepping through a list or slider, triggering a site shortcut. There are no explicit exclusions or named alternatives (e.g. 'to enter text, use cotlet_browser_type'), which keeps it short of a 5.

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

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 description's added value is in the details it supplies: the 20,000-character cap, that open dialogs are listed first, and that field values, cookies and storage are never returned. The one omission is what an agent should do when the cap truncates the page — there is no guidance on continuing past 20k characters.

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 primary behavior and return payload, then the usage rule and the exclusions. Every clause carries information; there is no filler.

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

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

With no output schema, the description does the work of describing the return shape (text plus a numbered control list) and the privacy exclusions, which is adequate for a one-parameter read tool. The gap is the truncated-content path: nothing tells the agent how to read beyond the 20,000-character limit.

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% for the single `element` parameter, so the baseline is 3. The description adds only a parenthetical gloss on what an element can be ("a dialog, a form, a list"), which is mildly helpful but largely restates the schema's "Read only inside this element."

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 whole current page: its text (up to 20,000 characters) and a numbered list of its links, buttons, fields and other controls" names a specific verb and resource and enumerates the exact return contents. It also distinguishes this full-page read from the narrower `element` mode and, implicitly, from capture-style siblings like screenshot or find.

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 on a new page or when a step's answer is not enough" gives an explicit trigger, and the `element` clause states the alternative and its scope. It stops short of routing against other siblings such as cotlet_browser_find, cotlet_browser_evaluate or cotlet_browser_screenshot, which an agent may also consider for inspecting a page.

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, open-world, so safety is covered. The description adds genuinely useful behavior beyond that: the output is a JPEG, and it captures only the *visible* part of the page (viewport, not full page), which an agent needs to know before attempting coordinate clicks.

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 what is returned front-loaded before the usage guidance. No filler or repetition of annotation facts.

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 parameterless, no-output-schema tool, this covers the essentials: format, viewport limitation, and how to consume the result. Minor gaps remain, such as whether scrolling (cotlet_browser_scroll) is needed to see the rest of the page and any image-size/compression caveats.

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. The mention of x/y image coordinates is not a parameter of this tool but usefully explains how this tool's output feeds the click/drag siblings.

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 precisely what comes back: a JPEG of the visible portion of the page. That implicitly distinguishes it from the text-oriented cotlet_browser_read, though it never names that sibling or uses an explicit verb like 'capture a 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?

It gives concrete when-to-use guidance ('boards, canvases, maps, charts and layout that the text does not show') and a follow-on workflow (click or drag using image x/y). It does not explicitly exclude text-only checks or point to cotlet_browser_read as the alternative, so it stops short of a full when/when-not statement.

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, open world), so the bar is lower; the description still adds real value by disclosing the lazy-load side effect and by describing the response ('the elements and text in view, with the same numbers'), which compensates for the missing output schema. It leaves undocumented what happens when conflicting parameters are supplied together (e.g. element plus direction and screens).

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 mechanism ('mouse wheel'), then ordered by mode, then the return note — a logical progression with no filler sentences. The telegraphic, backtick-heavy phrasing is dense but each clause carries information, so it stays readable rather than 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?

For a four-parameter, all-optional tool with no output schema, the description covers what it does, its side effects, and roughly what comes back. Remaining gaps are behavioral edge cases (precedence between element and direction/screens, what the shared numbering refers to) rather than core information an agent needs to invoke 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 baseline is 3, but the description genuinely adds combinatorial meaning the schema does not: which parameter pairs go together (screens qualifies down/up; element selects a scroll-until mode; inside targets a container instead of the page). The cryptic phrase 'with the same numbers' hints at a shared element-numbering convention without explaining it, keeping this just short of 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?

Opens with a specific verb and resource ('Scrolls with the mouse wheel') and enumerates the four supported modes (down/up by screens, top/bottom, until element in view, inside a container), which an agent can map directly onto the enum. It does not explicitly name sibling tools (e.g. cotlet_browser_read, cotlet_browser_wait) or state how it differs from them, so it stops short of full sibling differentiation.

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

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

'Content that loads on scroll appears' implies the main motivating use case (lazy-loaded or infinite-scroll content), but the description never states when to choose scroll over cotlet_browser_read, cotlet_browser_wait, or cotlet_browser_find. No exclusions or prerequisites (e.g. a page must already be open) are given, so usage is only implied.

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

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

Annotations already declare the full risk profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, non-idempotent), so the description needn't restate safety. What it does add is genuinely useful: 'Answers the page after it: the elements and text in view, with the same numbers' discloses the return shape and that element numbering is stable across steps, which matters because there is no output schema. It does not say whether selection waits for navigation or submits a form, which is the main residual risk for a destructive browser 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?

Three short sentences, front-loaded with the core action, then the exception case, then the return behavior. No filler, and the numbered-element contract is stated once without repetition.

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 covers the return value, and the dialog parameters are fully documented in the schema. The remaining gap is timing/side effects – whether the step waits for load and whether a selection can submit or navigate – but for a single-element browser action this is close to complete.

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

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

Schema coverage is 100%, so baseline would be 3, but the description earns above baseline by disambiguating `option`, whose schema text is merely 'The option.' – it clarifies that either the visible label or the underlying value is accepted. It also reinforces that `element` is the number from the previous step's answer, tying parameters to the read/select numbering loop.

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 (chooses) and a specific resource (an option in drop-down `element`), and the parenthetical 'its label as listed, or its value' pins down what an option is. It is clearly distinguishable from cotlet_browser_click only indirectly, via the 'home-made drop-down' caveat rather than an explicit contrast.

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 real branch condition: use this for a native drop-down, but for a home-made drop-down 'click it, then click the option' – effectively routing the agent to cotlet_browser_click. It stops short of naming that sibling or stating what happens when the element is not a list at all.

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

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

Annotations already declare destructive/open-world/non-idempotent, and the description earns extra credit on top: it says existing content is replaced, refuses sensitive fields, defines tab/newline interpretation inside `text`, and states the page is re-read afterward. That is real behavioral context an agent cannot get from the annotations alone.

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

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

Front-loaded with the core behavior and no filler sentences; every clause adds an actionable fact. It is densely packed, though — clauses like 'there a tab in `text` presses Tab and a line break Enter' take effort to parse, costing a bit of readability.

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 tells the agent the call answers with the page's elements and text using the same numbering — critical for continuing a numbered-element workflow. Combined with the sensitive-field refusal and dialog behavior, nothing essential is missing for a 6-parameter mutating 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 the baseline is 3, but the description adds meaning the schema does not: `element` omitted means type at focus, `submit` means Enter, and tabs/line breaks in `text` become key presses so one call can fill a table. Only `dialog`/`dialog_text`/`slowly` are 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?

States a specific verb and resource ('Types `text` into field `element`, replacing what it held') and immediately distinguishes scope from the sibling `fill_form`. The focus-based mode is named explicitly, so an agent can tell exactly what this tool does versus fill_form or press.

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

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

Gives explicit routing: several fields → fill_form; no element → types at focus; spreadsheet cells and editors that don't number reads → click first. It also flags exclusions (password/card/one-time-code fields are refused), which is a rare and valuable when-not-to-use clause.

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 genuinely new behavior: the 10-file and 20 MB caps, the two accepted file-reference shapes, and that it returns the page state afterward ("the elements and text in view, with the same numbers"). It does not say what happens on partial failure or oversized files, which is the remaining gap.

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

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

The action leads, followed by accepted file shapes, limits, and return behavior — a sensible order with no filler sentences. The dense colon/semicolon packing makes it read as one long clause chain, though nothing is strictly 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 usefully describes the return value (page elements and text with consistent numbering) and supplies size/count limits, which is most of what an agent needs for a browser file-input tool. Missing pieces are error handling and any prerequisite about the file input being present on the current page.

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 cannot express: the 20 MB per-file limit (only maxItems=10 appears in the schema) and the oral-form distinction between a public `url` and a Cotlet `file_id`. The `element` numbering hint is already in the schema, so it is repeated rather than added.

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 concrete verb and target ("Puts files into file field or upload button `element`"), which tells an agent exactly which page control is being acted on. It does not name the sibling `cotlet_upload_file`, which is the natural confusion point since the `file_id` form implies that tool runs first; only the phrase "a file uploaded to Cotlet" hints at the ordering.

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

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

Usage is implied rather than stated: files must already exist as a public URL or a prior Cotlet upload, and the `element` must come from the last read/step answer. There is no explicit when-to-use / when-not-to-use guidance and no pointer to `cotlet_upload_file` for the upload-to-Cotlet step or to `cotlet_browser_read` for refreshing element numbers.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description usefully discloses that the call also returns the page state afterwards — a non-obvious side effect — but omits the critical behavior on timeout: it says it 'says whether the text appeared,' yet not whether a miss raises an error or returns normally.

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, with the timing constraints packed parenthetically rather than in a separate paragraph. The closing phrase 'with the same numbers' is cryptic — it likely refers to another tool's element numbering without naming it, which forces a guess.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so only vaguely ('the elements and text in view, with the same numbers'). The timeout-failure semantics are unaddressed, which for a wait tool is the single most operationally important detail.

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% but the schema text is nearly content-free ('At most.'), so the description genuinely adds meaning: default 5 seconds, ceiling of 20, and that `text` is optional so the timeout can be used alone. It does not explain units or resolution beyond seconds, but that is minor.

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 ('Waits until `text` shows on the page') plus its two modes (text+timeout, or timeout only), which distinguishes it cleanly from polling-free siblings like cotlet_browser_read. It never names a sibling tool, so an agent must infer the boundary from the phrase 'for results that load slowly'.

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 results that load slowly' gives a clear triggering condition for using this instead of reading immediately. It stops short of explicit when-not guidance (e.g., don't wait if content is already present, pair with cotlet_browser_find for lookups), leaving some 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 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.

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds genuinely new behavioral facts: about 30 cards per read, the feed changes through the day, and a read is cached/reused for up to 15 minutes per country and language. It also discloses provenance (home IP in the country, unauthenticated NTA page), which an agent needs to interpret staleness and representativeness of results.

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 sentences, front-loaded with the core action and returned fields, with provenance and caching after. It is dense rather than padded, though the country/language default is stated twice (once narratively, once implicitly in the params) 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?

With no output schema, the description usefully enumerates the returned card fields (position, title, publisher, URL, domain, type, age, image) and covers freshness and caching. It does not say what happens for an unsupported or tiny country/language combination (empty feed vs error), which is the main 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 description coverage is 100% and already documents limit (counted from the top, default ~30), country (ISO alpha-2, home IP there), and language (BCP 47, default country language). The description mostly restates these ('in a country, in feed order', 'default feed of that country and language') rather than adding new semantics, 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 names a specific verb and resource ('The cards Google Discover shows right now in a country, in feed order') and pins down scope with 'with no Google account' and 'not anyone's personal feed and not data from a panel of users'. That implicitly separates it from collect_discover_cards and any personalization tool without needing to name 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?

Usage context is clear: use this for the un-personalized, country/language default feed read from a home IP, not for a user's personal feed or panel data. There is no explicit 'use X instead when…' routing to a named sibling, so it stops short of the top band.

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