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

With no annotations provided, the description carries the full burden and does so: it discloses that live=False is fast and side-effect free while live=True STARTS THE BROWSER, takes tens of seconds, and opens a visible window. It also explains what a 'skip' verdict means and why some checks do not apply, which is exactly the kind of behavior an agent cannot infer elsewhere.

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

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

Front-loaded with the purpose, then usage, then args, then return shape — a sound ordering. The 'check competitors cannot make' sentence is promotional filler rather than operational information, which keeps it from a 5, but nothing else 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?

There is no output schema, yet the description documents the return object (name, engine, live, summary, checks) plus the verdict vocabulary and the meaning of 'skip'. Combined with the side-effect disclosure for live=True, an agent has everything needed to decide and to interpret 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 0%, so the description must compensate and it does for both parameters. 'name' is anchored to the exact identifier format reported by profiles_list, and 'live' is given a default, a cost profile, and a decision rule rather than just a boolean definition.

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 ('run the consistency checkup on an identity') and immediately narrows the concept to fingerprint coherence. This is clearly distinct from siblings like proxy_check (proxy health only) and profiles_list (enumeration), so an agent can pick it 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 triggering conditions ('after changing an identity's proxy, and before trusting an identity with anything that matters') and an explicit exclusion for the expensive mode ('use it when you actually need measured proof, not for a routine look'). The live=False default is framed as the routine path, so the when/when-not decision is fully specified.

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 zero annotations the description carries the full burden and does so: quota consumption, fingerprint being frozen and byte-identical across restarts, failure-instead-of-overwrite on duplicate names, invalid engine rejection, and the account-safety caveat that force_dark alters page colors. It also enumerates the 409/403/422 failure modes with meanings.

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

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

Front-loaded with the core invariant before the args list, and the args section is scannable. Slightly verbose in places — the fingerprint explanation is restated across two sentences — but nearly every line adds decision-relevant information, so the length is mostly justified.

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

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

For an eight-parameter mutation tool with no annotations and no output schema, the description still supplies the return shape ({name, os, created}) and the full error taxonomy. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 0%, so the description must document all eight parameters — and it does: name (uniqueness semantics), engine (default fallback, rejection behavior, discovery via profiles_list), proxy (two concrete URL forms, direct-connection default, proxy_check prerequisite), group/tags/note (ledger phrasing, searchability, surfaced under `meta`), urls (startup tabs), and force_dark (default OFF, engine restriction, risk warning). This goes well beyond what the bare schema offers.

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

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

Opens with a specific verb and resource ("Create a new identity") and immediately explains the immutable-fingerprint model that distinguishes this tool from siblings like profiles_list or profile_settings. An agent knows exactly what it produces and why it can't be configured away.

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

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

Explicitly states when not to use it ("Do not create identities speculatively: they count against the installation's quota") and routes prerequisite checks to siblings ("Test a URL with proxy_check before binding it here", "The `engine` field in profiles_list shows what existing identities use"). The unique-name constraint also tells the agent what to do if a name exists.

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

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

With no annotations, the description carries the full burden and does so: it discloses the 409 refusal for running identities, the 404 for missing names, quota behavior while recycled, disappearance from profiles_list, and the loss of an older copy when a name collides in the bin. It also explains why no permanent-delete tool exists, which prevents a futile search.

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

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

Front-loaded with the safety-critical fact (recoverable, not erasure) and structured into short paragraphs that each carry distinct information. The closing "Fails with a readable message..." paragraph restates the 404 and 409 cases already covered above, which is mild redundancy.

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 single-parameter mutation with no annotations and no output schema, the description supplies everything an agent needs: preconditions, failure modes with codes, side effects, reversibility, and the deliberate absence of a hard-delete path. Nothing material is left to inference.

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

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

The single parameter has no schema description (0% coverage), and the description compensates by specifying it must be the identity name "exactly as profiles_list reports it" — a real disambiguation against display names or IDs. It stops short of stating case sensitivity or character constraints, so it is not exhaustive.

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

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

Opens with a specific verb and resource ("Move an identity to the recycle bin") and immediately scopes it against the obvious misreading with "this is not erasure." It also distinguishes itself from siblings by naming profile_restore, profiles_list and profile_stop in their relevant roles.

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 preconditions (stop a running identity with profile_stop first), explicit recovery path (profile_restore), and an explicit prohibition with a redirect ("Do not look for a way around this; tell the human instead"). The when-not and the alternative are both spelled out.

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

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

With no annotations, the description carries the full burden and does well: it discloses exactly what state is preserved (fingerprint, proxy binding, cookies, login state), asserts nothing is regenerated, and names both HTTP failure codes with their causes. It omits any mention of auth requirements or whether a restored profile auto-starts.

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 guarantee is front-loaded in the first sentence, the non-obvious consequence (nothing regenerated, no logged-in account lost) follows immediately, and Args/Returns are compact. No sentence is filler.

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

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

No output schema exists, so the explicit 'Returns {name, engine, created}' plus the two named error cases supply everything needed to call and interpret the result. For a single-parameter mutation this is complete.

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

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

Schema coverage is 0% and the schema types 'name' as a bare string, so the description must carry the semantics — and it does, clarifying that it is 'the trashed identity's name' rather than a live profile name. That distinction is the whole correctness hinge for this parameter.

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 ('Bring an identity back from the recycle bin') and immediately disambiguates from the creation sibling with 'restoring is not re-creating'. An agent can distinguish this from profile_create or profile_start without opening any schema.

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

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

The 404/409 failure conditions and their remedies ('rename or delete that one first, then restore') give clear preconditions for success. What it lacks is an explicit pointer to the sibling that would supply a valid name — trash_list — leaving the agent to infer how to discover trashed identities.

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 annotations, the description carries the full burden and does well: it discloses partial-update semantics, the side effect that sites may detect forced dark colors, the Chrome-engine restriction, and the delayed effect ('takes effect the next time the identity starts'). It omits permission/auth requirements, which is the main remaining gap.

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

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

Front-loaded summary sentence, then clearly delimited Args and Returns sections where every line adds information. Slightly long for a two-parameter tool, but no sentence is filler.

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

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

There is no output schema, and the description supplies the return shape ('{name, launch} with the launch settings now stored'). Combined with the partial-update and delayed-effect notes, an agent has everything needed to call this correctly.

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

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

Schema coverage is 0%, so the description must compensate and does: 'name' is pinned to the exact format profiles_list reports, and 'force_dark' is defined with its True/False semantics, the default of off, its visual consequence, and its platform restriction. Nothing about either parameter is left ambiguous.

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

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

States a specific verb and resource: 'Change a display setting of an existing identity', and clarifies it mutates launch settings of an already-created profile. An agent can distinguish it from profile_create and profile_checkup, though no sibling is named explicitly.

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

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

'Only the settings you pass are changed; everything else in its launch settings stays as it is' clearly frames this as a partial update. It also gives real exclusions for force_dark (Chrome-engine identities only, reserve for identities the user manages themselves, effective at next start), but never states when to prefer this over the other profile_* 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?

With no annotations, the description carries the full burden and does well: it enumerates returned fields, defines status semantics ('running' vs 'idle'), and adds a privacy guarantee that proxy credentials are never returned. It stops short of stating auth requirements or whether the list is paginated, so not 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?

Front-loaded with the core action and the routing instruction immediately after. The middle field-by-field enumeration overlaps with the existing output schema, making it slightly redundant, but each clause still adds useful selection context.

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

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

Complete for a zero-argument list tool: purpose, usage routing, return shape, status semantics, and privacy note are all present. Even though an output schema exists, the description's field summary and safety note ensure an agent can select and rely on it without opening the schema.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, though it does not explicitly say 'no arguments.'

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

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

States a specific verb and resource ('List every identity in this installation') plus the scope 'with its live status,' which distinguishes it from siblings like profile_start and profile_create. An agent can immediately tell this is the enumeration tool.

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

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

Explicitly says 'Call this first to find the exact name to pass to profile_start / profile_stop' and warns that names are case-sensitive. It names the downstream alternatives and the condition that selects them, leaving nothing 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?

With no annotations present the description carries the full burden and does: it discloses that the frozen fingerprint, exit proxy, and cookies persist across starts, that re-starting an open session is a no-op, and the exact failure modes (404 unknown identity, 429 session cap, daemon down). It also explains the conditional/unreliable nature of cdp_endpoint with reason-code enumeration and the detection risk of driving a session externally.

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

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

Front-loaded with the core action and return value, then Args, Returns, and caveats in a sensible order. Every section earns its place, though the cdp reason-code list (external_debug_off, external_debug_not_granted, not_supported_for_engine, starting) is dense and arguably belongs in return-value documentation rather than the tool description.

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

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

No output schema and no annotations, so the description must supply the return contract itself — it does, enumerating name, opened_at, idle_seconds, url, cdp_endpoint, cdp_unavailable, and cdp_note. Combined with the failure modes and the persistence semantics, an agent has everything needed to invoke and interpret 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 0%, so the description must document both parameters, and it does: 'name' is pinned to the exact string profiles_list reports (a useful cross-tool contract not in the schema), and 'headless' gets its default plus a concrete recommendation for login-shaped work. This adds genuine meaning beyond the bare type/default in the schema.

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

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

States a specific verb and resource ('Open a browser session for an identity') plus what it returns ('the endpoint to drive it'). It is clearly separable from siblings like profile_create (makes the identity) and profile_stop (closes it), and it also states the idempotent no-op case so the agent knows re-invocation is safe.

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 conditional guidance: headless defaults to False because 'headed... is what you want for anything login-shaped,' and it names the alternative driver path ('Prefer the daemon's own commands over attaching to cdp_endpoint') with the reason. It never explicitly routes to profile_stop for closing or says when not to start a session, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses what survives (cookies and login state in identity storage), what is lost (form input), idempotency (no-op on an already-idle identity), the two distinct things that may be running and the ordering of shutdown, plus the two failure modes (unknown identity, daemon not running). This is exactly the context an agent needs before invoking a destructive-ish operation.

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

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

Well front-loaded: the core action and the state-survival rule come first, followed by the two-things-running explanation, then Args/Returns/Fails. It runs a bit long and the session-vs-identity fallback sentence is dense, but nearly every sentence adds actionable information rather than restating the name.

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

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

No output schema exists, so the description supplies return semantics itself, defining the `stopped` and `closed` fields and the already-idle case. Combined with explicit failure conditions and side-effect disclosure, an agent has everything needed to call this correctly without further exploration.

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 0%, so the description must compensate; it names the sole parameter and specifies its provenance ('exactly as profiles_list reports it'), which tells the agent where to obtain a valid value. It could have added case/normalization rules, but the sibling pointer covers the main risk.

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

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

States a specific verb+resource (stop an identity's browser) and immediately qualifies scope with 'however it was started', which distinguishes it from profile_start and the session_* tools. The second paragraph clarifies that it closes either the daemon-driven warm session or a desktop-launched window, so there is no ambiguity about what object is being acted on.

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

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

Gives clear positive guidance ('Stop identities you are done with') and explains why, plus the operational rationale that an idle identity frees the warm browser. It does not contrast with profile_delete or profile_restore in the sibling list, so the agent must infer that stopping is not the same as deleting/trashing — a small but real gap.

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 annotations, the description carries the full burden and does so well: it discloses the return shape for both success and failure, warns that a dead proxy returns ok:false rather than erroring ('an ANSWER, not a failure'), and notes country may be null on a working proxy. It also notes no identity/auth is needed.

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

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

Front-loaded with the purpose and the key warning, then structured Args/Returns. Slightly long and the Args block partially duplicates the schema, but every line adds usable 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?

No output schema exists, but the description documents the return fields (ok, exit_ip, country, latency_ms, error) and their edge cases. Nothing an agent needs to call and interpret this tool 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 0% for the single required url parameter, but the description compensates with concrete format examples (http with embedded credentials, socks5). A 4 rather than 5 because port/credential edge cases and validation rules are not described.

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: 'Test a proxy URL and report where it actually comes out.' No sibling tool does proxy testing, so this is unambiguous and immediately distinguishable from profile_* and session_* tools.

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

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

Explicitly says to use it before binding a proxy with profile_create, gives the rationale (failure here is free, failure mid-signup costs the account), and explicitly states what it does NOT cover (per-identity check not exposed). This is textbook when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the session precondition, the return value ({ok: true}), and the exact failure modes with status codes (409 not-open, 404 missing identity, 502 no match/timeout). It leaves out what happens on multiple matching elements and whether the click waits for navigation, which are meaningful gaps for a browser click.

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

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

Front-loaded with the core action, then prerequisites, then parameter meaning, then return/error contract. Sentences are short and every one adds information an agent needs, with no restatement of the title or filler.

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

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

For a two-parameter browser action with no output schema and no annotations, the description covers preconditions, error codes, and the return shape, which is nearly everything needed. The remaining hole is behavioral on the happy path: no statement about which element wins when the selector matches several, or whether a click that triggers navigation is awaited.

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 0%, so the description must compensate, and it does: `name` is defined as the identity name exactly as profiles_list reports it (a real semantic constraint, not just a type), and `selector` is defined as CSS with concrete examples and explicit non-examples (not XPath, not role/name). This adds substantial meaning beyond two bare strings.

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 (click) and resource (an element on the session's current page) plus the locating mechanism (CSS selector). It explicitly contrasts itself with XPath and role/name lookups, which are what sibling tools like session_snapshot or role-based helpers would provide, so an agent can identify it without opening the schema.

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

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

Gives a clear precondition ("Requires a session opened with profile_start first") and redirects the agent to session_snapshot when it needs to discover an element. It doesn't state when to prefer an alternative over clicking, e.g. session_eval for scripted interactions or session_fill_selector for inputs, but the usage context is otherwise unambiguous.

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

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

No annotations exist, so the description carries the full burden, and it does most of the work: it discloses that dialogs are left open and block the page, that sibling tools return 409 with a specific message shape, that beforeunload from your own navigation is auto-accepted, and what failure codes mean (409 no dialog open, 409 session not open → call profile_start, 404 unknown identity). The only gap is it doesn't say whether the answered state is persisted or what happens on concurrent sessions.

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

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

Front-loads the core action in the first sentence, follows with the blocking context that justifies its existence, then structured Args / Returns / Fails blocks. Every sentence adds distinct operational information — none is filler.

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

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

With no output schema, the description supplies the return shape ({ok, action, type, message}); with no annotations, it supplies blocking semantics and error behavior; with no schema descriptions, it defines all three parameters. Prerequisites (profile_start) and failure codes are covered, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate fully, and it does: 'name' is defined as the identity name exactly as profiles_list reports it; 'action' is constrained to 'accept' (OK/Leave) or 'dismiss' (Cancel/Stay); 'prompt_text' is scoped to prompt() dialogs and its default behavior (accept default value when omitted) is spelled out.

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 ('Answer the JavaScript dialog ... open on the session's page') and enumerates the dialog types it handles (alert, confirm, prompt, beforeunload). It also distinguishes itself from the other session_* tools by explaining that they fail while a dialog is open, making selection 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?

Explicitly says when to call it ('while one is open the page is blocked and the other session_* tools fail with 409 ... Call this to answer it, then retry'). It also names the exception — beforeunload triggered by your own session_goto or click is auto-accepted and never appears here — which prevents a whole class of wrong calls.

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 annotations, the description carries the full burden and does so well: it discloses that page-JS errors return an {ok:false, error, error_type} envelope rather than raising, versus 409/404 conditions that do raise. It also warns that the result type is not necessarily a string, which prevents a common misparse.

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

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

Front-loaded with the core action and the error-handling caveat, and the Args block adds real semantics rather than restating types. Slightly longer than necessary — the Args section partly repeats parameter mentions in the prose — 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?

No output schema exists, yet the description fully specifies the return envelope, the variable type of `result`, and the two distinct failure modes. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it defines `name` as the identity name exactly as profiles_list reports it, and gives two concrete `expr` examples ("document.title", "document.querySelectorAll('a').length").

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 ('Evaluate') and resource ('a JavaScript expression on the session's current page'), which separates it cleanly from siblings like session_goto, session_click_selector, or session_snapshot. An agent can pick this tool 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?

Explicitly names the prerequisite ('Requires a session opened with profile_start first') and reinforces it in the failure path ('409 — call profile_start first'). It doesn't contrast against alternative page-inspection siblings like session_snapshot, but the usage context is unambiguous.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the React/Vue-compatible Playwright behavior, the session prerequisite, the replacement semantics of the text field, and the failure codes 409/404/502 with causes. It also states the successful return shape {ok: 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?

The description is front-loaded with the core action, followed by important behavioral context, an Args section, and failure behavior. Despite its length, every sentence adds information not present in the bare schema 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 three-required-parameter mutation tool with no annotations, no output schema, and no schema descriptions, the description is complete: it covers prerequisites, parameter meaning, behavioral traits, success return, and error mapping. An agent has enough information to invoke it correctly and interpret common failures.

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 0%, so the description must compensate, and it does for every parameter. It explains name as an identity exactly matching profiles_list, selector as a CSS selector (not XPath), and text as replacing existing content.

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: fill a text field on the session's current page, located by a CSS selector. It distinguishes this from direct DOM manipulation by noting Playwright's fill() handles React/Vue-controlled inputs correctly, and it explicitly rules out XPath selectors.

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 a session must first be opened with profile_start and gives a 409 fallback instruction. It also notes the selector must be CSS, not XPath. It does not explicitly route the agent to sibling tools like session_click_selector, but the fill-specific context is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool mutates an already-open session rather than creating state, documents the return shape ({url}: post-navigation URL), and enumerates two concrete failure modes with status codes (409 session not open, 404 identity missing). It stops short of describing things like whether it waits for load completion or how it affects open tabs, leaving a small residual 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?

Front-loaded with the action and the precondition, then cleanly sectioned into Args and Returns/Fails. Every line carries information; the only minor cost is mild redundancy between the prose precondition and the 409 note.

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 2-parameter, no-output-schema tool, the description supplies everything needed: precondition, both parameter meanings, return value, and error semantics with codes. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: `name` is tied to the exact identifier format reported by profiles_list, and `url` is given a concrete example. It adds real disambiguation value beyond two bare strings, though it does not say whether URLs without a scheme are normalized.

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 — 'Navigate a session's current page to a URL' — which is clearly distinct from siblings like session_switch_tab or profile_start. An agent can select this tool without opening any schema.

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

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

It states the prerequisite explicitly ('Open the identity's session with profile_start first') and adds the crucial exclusion that it does not open a session itself. It also names the exact recovery action when the 409 precondition fails, so both when-to-use and what-to-do-on-failure are covered.

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 annotations, the description carries the full burden and does well: it discloses the return value ({ok: true}), the 409/404 error semantics, and the session prerequisite. It does not state whether the press waits for any resulting navigation, which leaves a small gap for an input tool.

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

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

Front-loaded with the core action, then structured Args and Returns sections with zero filler. Marginally longer than strictly needed, but every line 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?

No output schema exists, and the description supplies the return shape and error codes. Combined with the prerequisite and key-format guidance, an agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate and does: 'name' is defined as the identity name exactly as profiles_list reports it, and 'key' is defined as a key or chord with concrete Playwright examples ('Enter', 'Tab', 'Control+A'). This adds real semantics well beyond the bare string 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: 'Press a keyboard key on the session's current page', with the target clarified as 'whatever is focused'. It is distinguishable from siblings like session_click_selector and session_fill_selector, though it never names them 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?

Clearly states the prerequisite ('Requires a session opened with profile_start first') and the failure path if that precondition is unmet (409 — call profile_start first). It gives clear context for use but does not contrast against alternative input tools such as session_fill_selector.

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 annotations, the description carries the full load and does well: it discloses the prerequisite session state, the failure modes with concrete status codes (409 when no session, 404 when the identity does not exist), and that errors are readable rather than opaque. The remaining gap is that it says nothing about snapshot size or possible truncation of large accessibility trees, which matters for a tool that returns a whole page tree.

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

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

Front-loaded with the purpose, then usage, then Args, then Returns/errors — an agent can stop reading at any point and still know enough to act. Slightly redundant in restating the 409 condition both in the prerequisite line and the Returns block, but that repetition is cheap and serves the error path.

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 definition covers purpose, prerequisite, return shape (accessibility tree as text), and both error paths — nearly everything needed to invoke it correctly. The only omission is guidance on payload size or what to do if the tree is very large, a minor gap against an otherwise complete entry.

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 0% and the single `name` property has no description, so the description must compensate — and it does, defining `name` as the identity name "exactly as profiles_list reports it," which tells the agent both the value's source and its exact-match requirement. It stops short of stating whether the name is case-sensitive or what happens on a near-miss, but the discovery pointer is the important part.

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 — take an accessibility-tree snapshot of the session's current page — and explicitly positions it as "the primary way to see what is on a page before acting." It routes the agent toward the consuming siblings (session_click_selector, session_fill_selector), so it is distinguishable from session_eval, session_tabs, and the profile_* tools 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 (read this to find roles/names/selectors before clicking or filling) and a hard prerequisite ("Requires a session opened with profile_start first"). It also names the specific consumers of the output, which is exactly the alternative-routing an agent needs.

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 annotations, the description carries the full burden and does most of it well: it discloses the returned shape ({index, url}), the three failure modes with their HTTP codes (409 not-open, 404 unknown identity, 422 out-of-range index), and the snapshot staleness hazard. It stops short of saying whether the switch itself has side effects on the page (e.g. load/focus events) or how it behaves if the index is stale but still in range.

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

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

Front-loaded with the one-line purpose, then prerequisite, then a compact Args/Returns block, then failure modes. Every sentence adds information the agent cannot get from the schema; nothing is redundant filler.

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

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

No output schema and no annotations, so the description must cover return value, preconditions, and errors on its own — and it does, naming the exact response object and each error code. For a two-parameter session tool this leaves nothing an agent needs 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 description coverage is 0%, so the description must supply all parameter meaning, and it does: `name` is the identity name exactly as profiles_list reports it, and `index` is the tab index obtained from session_tabs. It also documents the validity window of `index`, which the bare integer type cannot convey.

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

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

States a concrete verb and resource: bring one of the session's open tabs to the front and make it active. That clearly separates it from session_tabs (which enumerates) but it never names the neighboring navigation tool session_goto, so an agent must infer that distinction from the sibling 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?

Explicitly states the prerequisite (a session opened with profile_start) and where the `index` value must come from (session_tabs), plus the crucial ordering caveat that indices are only valid as of that snapshot and shift when tabs open or close. That is exactly the when-and-how guidance an agent needs to avoid a wrong-tab invocation.

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 annotations, the description carries the full burden and does so: it discloses the session-state prerequisite, the two failure modes with their status codes (409 not-open, 404 unknown identity), and that errors are returned as readable messages. It also describes the return payload shape.

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

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

Front-loaded with purpose, then prerequisite, then usage, then args and returns — a clean progression with no filler. The Args/Returns block formatting is slightly verbose for a single parameter, but every line 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?

No output schema exists, and the description still documents the return value ({tabs, active} with element shape), the error contract, and the required prior state. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0% and the single parameter has no schema description, so the description must compensate — it does, defining 'name' as the identity name 'exactly as profiles_list reports it', which tells the agent where to obtain the value.

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

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

States a specific verb and resource ('List the session's open tabs') plus a scoping detail (active tab marked). The following sentence explicitly distinguishes it from siblings session_switch_tab and profile_start, so an agent can route 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 ('Use this to find the index to pass to session_switch_tab') and an explicit prerequisite ('Requires a session opened with profile_start first'). The 409 failure message also reinforces the alternative ('call profile_start first').

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it declares the operation read-only, explains that listed entries are still recoverable with cookies and login state intact, and specifies ordering and empty-list 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?

The description is front-loaded with the core purpose and uses short paragraphs that each add distinct value: recovery use case, relation to siblings, return fields, ordering, empty state, and intactness of restored data.

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?

Given a zero-parameter tool with an output schema and no annotations, the description is complete enough for correct selection and invocation. It explains why the tool exists, how it relates to sibling tools, what the output contains, and what an empty result means.

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 input parameters, so there are no input semantics to clarify beyond the baseline. The description instead adds useful output orientation by naming the fields each entry carries and the newest-first ordering.

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 lists identities currently in the recycle bin and clarifies that these are recoverable. It explicitly distinguishes the tool from profiles_list by noting deleted identities do not appear there, and names profile_restore as the paired action.

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 case: find out what can be restored, because deleted identities are absent from profiles_list and otherwise a caller could only restore a name already known. It also directs the agent to pair this tool with profile_restore.

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