MarketSharp MCP Server and API by Cotlet

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 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?

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?

The annotations flag destructiveHint=true, and the description earns that by saying the target's content is replaced, plus the refusal policy for sensitive fields and the fact that a page read is returned afterward. These are policies and consequences the annotations cannot express, so the description carries real additional weight.

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 and its Enter behavior are front-loaded, and every sentence carries operative content. It is dense and slightly run-on in places ("Answers the page after it: the elements and text in view, with the same numbers"), which costs some readability but not correctness.

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 explains what comes back — the elements and text in view with the same numbers — so an agent knows the return value feeds later calls. Combined with refusal rules and focus/spreadsheet edge cases, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: a tab in `text` presses Tab and a line break presses Enter, and omitting `element` types at the current focus like a person after clicking. The `app` and `dialog` parameters are left entirely to their schema text, keeping this below 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 ("Types `text` into field `element`") plus the side effect of `submit`, and explicitly routes the multi-field case to `cotlet_browser_fill_form`. An agent can distinguish this from fill_form, click, and press 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 explicit when-to-use rules: one field here vs. several with fill_form, omit `element` when the target has no read number (Google Sheets/Docs) after clicking the spot, and the tab/newline convention that lets one call fill a table. It also names an exclusion — password, card, and one-time code fields are refused.

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?

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 the genuinely load-bearing fact that the tool 'opens nothing by itself' — a caller who misses that would wrongly assume the note is created. It also explains why browser automation is required (the official OData API is read-only and admin-gated), which is useful context 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?

Purpose and the 'returns instructions, does nothing itself' caveat are front-loaded in the first two sentences. The third sentence on MarketSharp's OData API is slightly tangential but earns its place by explaining why the browser path is necessary.

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, no-output-schema tool, the description covers what is returned and the follow-up step well. It does not address how the agent should target a specific contact/job when the returned guide is generic, nor how the guide's scope relates to the user's account — a real gap for a note-adding workflow.

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 schema-coverage baseline of 4 applies. The description does not need to explain argument syntax, though it leaves open how the target record or account is identified.

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 ('Add note in the user's own MarketSharp account') and immediately clarifies the unusual mechanic: it 'Returns how to do it in MarketSharp step by step' rather than performing the write. It does not explicitly contrast with the sibling marketsharp_* tools, so an agent must infer whether those are API-backed operations while this one is a guide.

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

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

It gives clear chaining guidance: call this to get screens/buttons/fields, then execute with the cotlet_browser_* tools in the MarketSharp Cloud Browser. What is missing is any exclusion or alternative — for example, when a generic guide tool (cotlet_app_guide) would suffice instead of this MarketSharp-specific one.

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 it discloses the key behavioral fact that "opens nothing by itself," so the agent knows no side effect occurs, and it explains why browser automation is required (the official OData API is read-only). This is consistent with readOnlyHint=true and adds real context. Minor gap: it doesn't describe the shape or length of the returned step-by-step text.

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 message is front-loaded, but the text is a rambling run-on that stitches three ideas together with semicolons, and the closing API sentence is a fragment ("MarketSharp's official API: MarketSharp has a read-only OData API..."). The API detail earns its place as justification but could be one clause instead of two.

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 zero parameters, no output schema, and a simple read-only guidance behavior, the description covers what an agent needs: what it returns, that it has no side effects, and which tools to use next. Only the return format of the instruction text is left unspecified, which is a small 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?

The tool takes zero parameters, so the baseline is 4 and the description has nothing parameter-related it must compensate for. Nothing here adds confusion about inputs.

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

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

The description gives a specific verb and resource ("Create lead in the user's own MarketSharp account") and immediately clarifies that the tool does not actually create anything but returns step-by-step instructions. This resolves the tension with the name, though the name itself still reads like a mutating action, which costs a point.

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

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

It states the follow-up path explicitly: after receiving the steps, execute them "with the cotlet_browser_* tools in the user's MarketSharp Cloud Browser." That routes the agent to the right sibling family. It does not, however, say when to prefer this over cotlet_app_guide or cotlet_apps, both of which plausibly overlap.

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 (readOnly, idempotent, non-destructive, closed-world), it adds two facts the annotations cannot convey: the tool 'opens nothing by itself' (pure guidance, no side effects on the account) and that MarketSharp's official API is a read-only OData API enabled by admins under API Maintenance. The second point explains why browser automation is required, which is genuinely useful planning context. It does not describe the shape of the returned steps (no output schema exists), which holds it at 4.

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 outcome and the no-side-effects caveat, which is good. The final sentence is a long run-on carrying the API note plus a parenthetical '(checked 11 Oct 2026)' that reads as a maintenance stamp rather than agent-relevant information and slightly dilutes focus.

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 it does: step-by-step screens, buttons, and fields. It also closes the loop on next actions via the cotlet_browser_* tools. Minor gap: it does not state prerequisites such as being signed in to the MarketSharp Cloud Browser before the guide is actionable.

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

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

Zero parameters, so there is no parameter meaning to add; the baseline for a no-param tool is 4. The description correctly implies no inputs are needed, though it does not say whether the target contract/account must be identified conversationally or is inferred from the connected account.

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 resource (contract status) and then discloses the actual delivery mode: it 'Returns how to do it in MarketSharp step by step (screens, buttons, fields) and opens nothing by itself.' That resolves the ambiguity a name like get_contract_status would otherwise create (guide vs. data fetch). It does not differentiate itself from nearby siblings such as cotlet_app_guide or marketsharp_list_jobs, keeping it below a 5.

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

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

It gives an explicit execution sequence: call this, then 'do it with the cotlet_browser_* tools in the user's MarketSharp Cloud Browser.' That is real routing guidance rather than implied usage. It stops short of saying when NOT to use it or naming a competing alternative for the same task.

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, it adds two genuinely useful behavioral facts: the tool "opens nothing by itself" (no side effects, consistent with readOnlyHint) and the return is step-by-step UI guidance. The note that MarketSharp's official OData API exists but is admin-enabled read-only adds account-level context an agent would otherwise lack. It does not describe length or format of the returned steps, keeping it short of a 5.

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

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

The first two clauses are load-bearing, but the closing sentence about the OData API and its admin toggle is tangential to invoking this tool, and the "(checked 11 Oct 2026)" parenthetical adds noise. The key fact (no side effects, returns instructions) is not front-loaded but embedded mid-flow.

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 define the return value, and it only partially does ("step by step (screens, buttons, fields)") without saying whether any job records come back or what the steps look like. For a zero-parameter, read-only, non-open-world tool the safety picture is adequate, but the output contract remains under-specified against the "List jobs" framing.

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 and there is nothing further the description could clarify about inputs. No parameter claims are made that could confuse the agent.

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 opening states a specific verb and resource ("List jobs in the user's own MarketSharp account"), but the very next clause reframes the tool as returning "how to do it in MarketSharp step by step (screens, buttons, fields)" rather than job data. An agent cannot tell from the text whether it receives a job list or a procedural walkthrough, so the core purpose is left ambiguous despite the concrete wording.

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 follow-on path ("then do it with the cotlet_browser_* tools in the user's MarketSharp Cloud Browser"), which implies this is a prerequisite step. However, it never says when not to use it or how it differs from siblings such as cotlet_app_guide or marketsharp_get_contract_status, which plausibly serve overlapping lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context: it returns screens/buttons/fields guidance and performs no action itself, and it notes the official API is read-only. It does not explain the shape of the returned guidance beyond that summary, so it is helpful but not rich.

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 read-then-act split is front-loaded and useful, but the second sentence is long and clause-chained, and the closing sentence about the read-only OData API and its check date is tangential to calling this tool.

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

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

For a zero-parameter tool with no output schema, the description covers what it returns (step-by-step screens, buttons, fields) and how to proceed afterward. It omits how the target appointment is specified or scoped, which is a meaningful gap for an update-oriented 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?

With zero parameters the baseline is 4. The description correctly implies no inputs are required to obtain the guidance, though it never says how the specific appointment to update is identified, which is the one semantic gap.

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 ('Update appointment in the user's own MarketSharp account') and clarifies it is invoked from AI agents. It does not explicitly distinguish itself from siblings such as marketsharp_create_lead or marketsharp_get_contract_status, but the verb+resource pairing 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?

It clearly says the tool returns step-by-step instructions and that the actual update is done with cotlet_browser_* tools in the Cloud Browser, plus that the tool 'opens nothing by itself'. That is a clear use context, but there are no explicit when-not conditions or prerequisites beyond the user owning a MarketSharp account.

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