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

The description goes well beyond the annotations: it reveals that actions hit the live site, that submissions have real side effects, that the tool settles after acting, and that changed: false means nothing observable happened. It also explains that the result contains a fresh snapshot with @N refs, which is behaviorally important and not present in 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?

The description is dense but purposeful, front-loading the tool's purpose and return value before enumerating action-specific rules. It contains no filler, though the action-by-action list partially overlaps with the input schema's action enum description, so the overall length is a bit high but 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 a complex, destructive, live-action tool with 11 parameters and no output schema, the description covers all essential context: what each action does, how targets work, what the result contains, how to interpret changed: false, and when to stop. Nothing important seems missing for an agent to invoke it safely and 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 3, but the description adds genuinely useful action-specific semantics: fill replaces the value, type appends keystrokes, '@focused' types into the focused element without clicking, and scroll with neither target nor delta_y scrolls most of a screen down. This clarifies combinations that the schema alone does not fully express.

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: perform one input action on the active tab with human-like mouse and keyboard, then settle and return page state plus a snapshot. It enumerates the exact actions (click, dblclick, hover, fill, type, press, select, scroll), making it unambiguous and distinguishable from the sibling navigation, read, screenshot, and wait 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?

It explicitly says to use the tool for every click, form entry, and keypress, and it tells the agent what to do when changed is false: take a snapshot or wait instead of repeating the action. It also gives a critical boundary: stop before payments or final confirmations the user did not ask for, which is a clear when-not-to-use instruction.

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

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

Goes well beyond the annotations by disclosing isolated vs main world execution, promise awaiting, 30000-character truncation, and synthetic event caveats. The destructiveHint=true annotation is consistent with the ability to run arbitrary JavaScript that can mutate the page, and the description's warnings add valuable operational context.

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 dense but efficient; every sentence adds distinct value. The core capability is front-loaded, followed by usage guidance, execution context, caveats, and limitations in a logical order.

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 tool with no output schema and 4 parameters, the description covers execution semantics, return behavior, world visibility, event caveats, size limits, and data trustworthiness. Nothing critical for an agent to select and invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that expression can be a function called with args, promises are awaited so async polling is possible, and main_world changes page visibility.

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

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

States a specific verb and resource: runs JavaScript in the active tab and returns a JSON result. It also distinguishes itself from sibling tools by saying it covers structured data, page globals, and computed state that snapshot and surfsky_read do not expose.

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 use cases: read data not exposed by snapshot or surfsky_read. It also warns that element clicks and value assignment go through surfsky_act and fire synthetic events that bot detection flags, effectively steering agents away from using this tool for interaction.

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 important behavioral nuance beyond the annotations: 'A status of 200 does not prove the real page loaded: bot challenges and interstitials return 200 too, so check the title and snapshot for the expected content before repeating a submission.' It also discloses session-start-on-first-use behavior and the snapshot row limit. No contradiction with the annotations.

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

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

The description is front-loaded with the core operation and return payload, then moves to usage guidance, session behavior, and caveats. Every sentence earns its place, and the length is justified by the tool's complexity.

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?

Despite having no output schema, the description explains the return fields (final url, HTTP status, navigated, snapshot). It covers alternatives, session semantics, verification pitfalls, and snapshot limits. For a tool with six parameters and several sibling tools, this is remarkably 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?

The input schema already covers all parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds value by clarifying the snapshot limit ('up to 300 rows') and reinforcing the url/go mutual exclusivity and the default-session behavior, pushing it above 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?

The description uses a specific verb and resource: 'Open a URL in the session's active tab (or go back, forward or reload) and return where it landed.' It also names surfsky_scrape and surfsky_act, making clear this is the navigation tool for interactive pages, not the cheap read-only scrape 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 explicitly says when to use this tool: 'Use it for a page that needs clicks, scrolling, a form or a login; for a page you only need to read once, surfsky_scrape is cheaper and starts no session.' It also gives context on the default session and points to surfsky_snapshot when the 300-row snapshot limit is exceeded.

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, openWorld, and non-destructive behavior. The description adds meaningful context beyond that: truncation at line boundaries with a marker, the ability to recover remaining content by raising max_chars or using a selector, and the warning that content is page-controlled and arrives inside an untrusted-page-content fence. These details materially affect how an agent should handle results.

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

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

Every sentence earns its place: core purpose first, then usage context, then practical edge cases, then security handling. No redundancy with the schema, and the most important information is front-loaded.

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?

Despite having no output schema, the description explains what the tool returns, how output can be shaped, how truncation works, how to avoid it, and how to treat the content safely. Given the tool's moderate complexity, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the truncation marker and recovery strategy ('raise max_chars or pass a selector for the rest'), and it clarifies selector and only_main_content effects in operational terms. This pushes it above 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?

The description opens with a precise verb and resource: 'Read the active tab' with four concrete output formats (markdown, text, html, links). It also distinguishes itself from surfsky_scrape, making the tool's role immediately clear relative to 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?

Explicitly states when to use this tool ('after surfsky_navigate or surfsky_act to get the page's text') and when to prefer an alternative ('for a URL that needs no clicks or login, surfsky_scrape does the same without a session'). This gives an agent actionable routing guidance.

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

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

The annotations already mark this as read-only and idempotent, and the description goes beyond them: it discloses the throwaway browser, that no session is started, that a residential proxy is used, that challenge pages may return 200, that long text is truncated with a marker, and that each call bills one short session. No contradiction with 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?

The description is front-loaded with the core action and return formats, then adds targeted usage caveats and alternatives. Every sentence earns its place; the challenge-page warning, truncation behavior, and billing note are all decision-relevant rather than filler.

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

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

For a 15-parameter tool with no output schema, the description gives enough to invoke correctly: return formats, default behavior, URL normalization, challenge-page risk, truncation, billing, session semantics, and clear routing to sibling tools. Parameter details are fully covered by the schema.

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

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

Schema coverage is 100%, so the schema carries the parameter documentation. The description adds a few behavioral notes such as 'Text longer than max_chars is cut with a marker' and references profile_uuid for saved logins, but it does not substantially enrich parameter semantics beyond what the schema already provides.

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: 'Fetch one URL in a throwaway cloud browser and return it as markdown...'. It clearly distinguishes itself from interactive siblings by saying it is for when you 'only need to read a page' and names surfsky_navigate, surfsky_act, and surfsky_read as alternatives for interactive needs.

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 to use this tool ('Use it whenever you only need to read a page'), when not to use it (clicks, scrolling, forms, interactive login), and names the alternative tools. It also adds practical guidance about challenge pages and saved-login profiles.

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 signal safe read-only, idempotent behavior. The description adds behavioral context beyond those flags: default output is viewport JPEG, PNG is used for full page or element captures, and full-page captures can be large. It does not cover every possible failure mode, but given the strong annotation coverage this is sufficient context.

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-load the core purpose, then cover when to use it, the alternative, and a cost caveat. Every sentence provides distinct information and none are redundant with the 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?

Given the rich annotations, 100% schema coverage, and optional parameters, the description covers the key decisions an agent needs: what the image captures, what the output modes are, and when to prefer surfsky_read. The main omission is exactly how the image is returned (e.g., in-band image vs reference), but this is minor because the description says it is an image the agent can see.

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?

All three parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds extra meaning by tying selector/element capture to PNG output and full_page to a whole scrollable page, which slightly goes beyond the schema's individual field 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 description opens with a specific action ('Capture the active tab as an image you can see') and clarifies the resource and output types, distinguishing viewport JPEG from full-page/element PNG. It also positions the tool against surfsky_read ('for reading text... cheaper and exact'), so an agent can tell it apart from siblings without opening schemas.

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

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

It gives explicit use cases: checking a visual state such as a challenge page, layout, chart, or finding something not listed in the snapshot. It explicitly routes text-reading tasks to surfsky_read and cautions that full-page captures of long pages are large, which guides when to prefer other 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, idempotentHint, and non-destructive behavior. The description reinforces this with 'Read-only' and adds meaningful behavioral detail about what fields are included, such as 'owned' and 'default' flags, which goes 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?

The description is compact and front-loaded: the core listing action and output fields come first, followed by a one-word safety note and concrete use cases. Every sentence earns its place with no 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?

This is a simple, zero-parameter read-only tool with no output schema, and the description compensates by listing the returned fields and common purposes. It is complete enough for an agent to call it correctly, though it doesn't mention response format or potential pagination.

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 has zero parameters, so the schema provides complete coverage. Per baseline, a 4 is appropriate since the description doesn't need to add parameter 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?

The description clearly states a specific verb ('List') and resource ('the account's running sessions'), and enumerates the exact fields returned. It distinguishes itself from sibling session management tools by focusing on listing rather than starting or stopping sessions.

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 explicitly gives use cases: finding leaked sessions to stop and retrieving the default session's id. It does not mention alternatives or exclusions, but the intended usage is clear and actionable.

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 billing per minute, idle_timeout stopping, the about:blank starting page, the private screencast URL, and the persistence of real logins for profiles. This is rich behavioral context that annotations alone do not provide.

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 primary purpose and then groups usage guidance, lifecycle, and security considerations coherently. It is longer than necessary in places, but each sentence carries useful decision-making or safety 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 session-creation tool with no output schema, the description covers what is returned, how to act next, how to stop the session, billing implications, when to use it, and an important privacy/security constraint. An agent has enough context to invoke it correctly and decide whether it is needed at all.

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 all 12 parameters in detail. The description adds meaningful high-level guidance for profile_uuid and default session behavior, but does not systematically add per-parameter semantics 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 clearly states the tool starts a cloud browser session and returns a session_id, with a specific verb and resource. It distinguishes itself from sibling browser tools by explaining when an explicit session is needed versus when the default session suffices.

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 when-to-use conditions: saved profile, proxy location, fingerprint OS, parallel browser, or own session because other agents share the server. It also says when to skip it, and names the next step (surfsky_navigate) and terminal action (surfsky_session_stop).

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 indicate destructive, non-read-only, idempotent, and open-world behavior. The description adds valuable context beyond those flags: billing is stopped, repeats are safe, any account session id works, and cookies/logins are persisted on a normal stop. No statement 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?

Every sentence earns its place: purpose, usage triggers, idempotence, account scope, persistence, and default-session behavior. It is front-loaded with the core action and contains no filler or redundant restatement of 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?

For a single-parameter destructive tool with billing implications and no output schema, the description covers the essential operational context: why to call it, what it affects, what persists, what is safe to repeat, and what happens next. Nothing critical is missing for an agent to invoke 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% and already explains that session_id can come from surfsky_session_start, a result header, or surfsky_session_list. The description adds further useful semantics: it accepts any account session id, not only ones this server started, and mentions handling of the default session.

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

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

The description opens with 'Stop a session and its billing,' naming a specific verb, resource, and consequence. It also distinguishes itself from sibling session tools by framing it as termination/cleanup, and from the broader browser-action siblings by focusing on session lifecycle.

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 explicitly says to use this tool when a task is done or to clean up a leaked session found with surfsky_session_list. It also clarifies that stopping the default session is fine and that the next browser call starts a fresh one, giving an agent practical boundaries for safe usage.

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?

Even though annotations already declare readOnly/openWorld/idempotent/non-destructive, the description adds valuable behavioral details: refs are replaced by each snapshot, stale refs produce stale_ref, iframe and shadow-root contents are not listed, and find narrows without renumbering. No contradiction with 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?

The description is dense but efficient: it front-loads the output format, then covers staleness, filtering, inaccessible frame content, and alternative tools in four information-rich sentences. No filler or repeated schema text.

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

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

With no output schema, the description adequately explains return value format, ref behavior, failure modes, iframe limitations, and parameter subtleties. It also situates the tool among siblings. Nothing essential is missing for an agent to select and invoke 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 100%, so the input schema already documents find, limit, session_id, and interactive_only in detail. The description adds framing like 'find narrows the list without renumbering', but this largely reinforces rather than extends 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?

The description uses a specific verb ('List') and resource ('visible interactive elements... and headings of the active tab'), and specifies the exact output format as '@N role "name"' lines. It also distinguishes itself from sibling tools like surfsky_read and surfsky_screenshot by saying what this tool is for versus those.

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 explicitly says when to take a new snapshot (after navigation, tab switch, or changed:false), warns that acting on old refs fails with stale_ref, and points to alternatives for text and visuals. It gives clear guidance on when to use this tool versus siblings.

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 and idempotentHint. The description adds value by explicitly stating it starts no browser and is read-only, and by detailing what account and session information is inspected. No annotation 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 sentences with no redundancy. The tool purpose and content are front-loaded, followed by practical usage scenarios. Every clause contributes useful 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 no parameters and no output schema, the description fully covers what the tool returns and when to invoke it. An agent has enough context to select and call 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?

The tool has zero parameters, so parameter semantics are not burdened by schema gaps. The description appropriately focuses on behavior and output rather than param details.

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 clearly states the tool checks the Surfsky account used by this server, and enumerates the specific information returned (credentials, plan limits, proxy quota, and owned sessions with idle details). It is distinct from all sibling tools, none of which are described as account status.

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 explicit triggers: use it after auth/quota/plan_full errors or before starting parallel sessions to check plan capacity. It does not explicitly mention alternatives or when not to use it, but the guidance is clear and actionable.

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 meaningful behavior beyond the annotations: new makes the tab active, close defaults to the active tab, the first tab cannot be closed, refs are tab-scoped, and cloud sessions allow only five tabs. This gives the agent important operational context that annotations alone do not convey.

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

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

The description is compact, well-structured around actions and then usage guidance. Each sentence adds relevant information without redundancy, and the most important operational details are front-loaded.

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 the tool's complexity and the absence of an output schema, the description covers the key return fields for list, tab selection semantics, constraints on closing, tab-scoped refs, and the cloud limit. The guidance for when to use snapshot and navigate makes it sufficiently complete for an agent to invoke the 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?

The input schema already has 100% coverage with detailed descriptions, so the baseline is 3. The description adds extra semantics by noting that new makes the tab active, switch makes a tab active, and close defaults to the active tab, enhancing the schema's action 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 description clearly identifies the resource (tabs of a session) and the specific actions: list, new, switch, and close. It differentiates itself from siblings like surfsky_navigate and surfsky_snapshot by explaining tab-specific operations and the relationship between tabs and refs.

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 explicitly tells the agent when to use list followed by switch for popups or target=_blank links, and when not to close the first tab, instead navigating it. It also directs the agent to take surfsky_snapshot after switching because refs belong to a tab, providing clear routing to sibling 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: conditions are waited one after another with full timeout each, unmet conditions fail with a timeout and leave the page untouched, and the tool returns url and title. This goes well beyond the annotation baseline.

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 dense but every sentence earns its place: purpose, usage context, condition semantics, selector nuance, failure behavior, and alternative routing. It is front-loaded with the core behavior and does not waste 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?

Despite having no output schema, the description states the return values (url and title). Combined with the fully documented input schema and annotations, it covers the essential operational details: timeout behavior, failure mode, selector syntax, condition combinations, and when to use a sibling tool instead.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it distinguishes CSS selectors that work for not-yet-existing elements from @N and text=words that must resolve immediately, and it explains how multiple conditions are sequenced and each gets the full timeout. These are not obvious from the parameter definitions alone.

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

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

The description uses a specific verb and resource: 'Wait until the active tab meets a condition, then return its url and title.' It clearly distinguishes the tool's purpose from siblings by naming surfsky_evaluate as the alternative for script-only conditions and by focusing on waiting for asynchronous page states.

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 explicitly states when to use the tool: 'after an action or after a domcontentloaded navigation,' and gives a clear when-not: 'actions already settle on their own, so no wait is needed after every step.' It also names the alternative tool for conditions only script can check.

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