Aginx Browser

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

Annotations only provide readOnlyHint=false, so the description carries the behavioral burden. It clearly discloses the destructive clear behavior ('clear to delete rows'), notes the performance difference, and adds functional specifics like Chinese substring and English word full-text support. This is strong coverage, though it does not mention irreversibility or permission requirements.

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 dense sentences carry the core message: what the tool accesses, when to use it, and how the main query modes map to parameters. No filler, and the most important guidance 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?

For a 9-parameter tool with no output schema and read-write behavior, the description provides a strong operational overview and covers the main modes. Remaining parameter details (limit, since_hours, kind) are documented in the schema, so the description is sufficiently complete for selection and invocation.

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 genuine semantic value by mapping modes to parameters: query for full-text search, get for full cached content, stats for counts, clear for deletion. This goes beyond the individual schema descriptions.

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

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

States a specific verb and resource: 'Query the LOCAL CACHE of every page this server has fetched and every search it has run.' This clearly distinguishes it from siblings like fetch and search, making the tool's scope immediately obvious.

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 instructs the agent to 'Check here BEFORE re-fetching or re-searching' and contrasts the instant/free cache hit with a costly fresh fetch. This directly routes usage away from fetch/search when a cached result may already exist.

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

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

Annotations only provide a title, no readOnly/destructive hints. The description implies a mutating action (click) but doesn't disclose side effects like navigation, form submission, or whether it requires a session. It doesn't contradict annotations, but adds minimal behavioral context beyond the schema.

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

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

The description is a single, concise sentence that directly states the tool's purpose. No wasted words.

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

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

Given the tool's simplicity and full schema coverage, the description is adequate but lacks context about when to use it vs session_click, and doesn't mention potential side effects or return behavior. For a tool with no output schema and minimal annotations, it could provide more guidance.

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 documents all three parameters. The description adds no additional meaning beyond what the schema provides, so 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 clearly states the action ('Click an element on a webpage') and the method ('using CSS selector'). It distinguishes from siblings like session_click by implying a one-off action without session management, though it doesn't explicitly contrast with session_click.

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 implies usage for clicking elements on a webpage, but provides no explicit guidance on when to use this tool versus session_click or other session-based tools. It doesn't mention prerequisites like page load or session creation.

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 only a title annotation and no safety hints, the description carries the behavioral disclosure burden. It adds valuable traits: streaming to disk with no memory buffering, SHA-256 integrity verification, optional resume, and filename resolution precedence. It does not mention overwrite behavior or return values, but the provided details substantially exceed minimal expectations.

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 well-structured: core behavior first, then filename resolution, then clear usage guidance. Every sentence adds distinct value with no filler or 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 tool with five parameters, complete schema descriptions, and no output schema, this description explains the core behavior, filename precedence, and ideal use cases. It lacks explicit statements about return values or error handling, but these are not critical for correct invocation given the schema coverage.

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 the filename resolution order ('explicit param → Content-Disposition → URL tail') and the overall disk-streaming behavior, which helps the agent understand parameter intent more deeply than the raw property descriptions 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 clearly states a specific verb and resource: 'Download a file over HTTP(S)' with concrete details like streaming to disk, SHA-256 integrity hash, and resume capability. It also distinguishes itself from text-reading tools by specifying it is for when 'the agent wants the FILE saved, not its text content read,' which separates it from sibling tools like fetch.

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 usage guidance: 'Use for binaries, archives, datasets, documents - anything where the agent wants the FILE saved, not its text content read.' This clearly tells the agent when to use the tool and implies when not to use it, though it does not name a specific alternative sibling tool.

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

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

Annotations contain only a title, so the description carries full behavioral disclosure responsibility. It mentions async/Promise support but does not disclose side effects such as page navigation, DOM mutation, or whether a fresh page or existing session is used.

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

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

Two sentences, front-loaded with the core purpose. Every word earns its place; no filler or 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?

The tool loads a URL and has a wait_secs parameter, but the description omits the URL-loading behavior, execution context (standalone vs session), and return value details. The sibling 'session_eval' highlights a key distinction that is not addressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats async/Promise support already present in the schema and adds no new parameter context or examples.

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

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

The description clearly states the tool executes JavaScript on a webpage and returns the result, with a specific verb and resource. However, it does not distinguish from sibling tool 'session_eval', which likely performs a similar action within a session context.

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

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

No guidance is provided about when to use this tool versus alternatives. There is no mention of session vs standalone contexts, prerequisites, or exclusions, leaving the agent to infer usage from the schema.

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 discloses the rendering pipeline: static pages via plain HTTP at ~100ms, JS pages via full browser, and explains the render_tier behavior including that the 'http' tier 'refuses the upgrade'. This is substantial behavioral context beyond the readOnlyHint annotation and tells the agent what actually happens during a fetch.

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, each with a distinct job: what the tool does, when to use it, and how the rendering tiers behave. No filler, and the most important scoping 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?

Covers purpose, usage scope, rendering behavior, and output format options, with the schema covering all parameter details. It does not explicitly address how fetch differs from session_navigate or whether results are cached, but the readOnlyHint and 'READ' framing are enough for correct invocation.

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 baseline is 3. The description adds a small extra nuance for render_tier ('refuses the upgrade') and summarizes the format choice, but doesn't elaborate on the other nine parameters beyond what the schema already documents.

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 ('Fetch') and resource ('a webpage') and explicitly says it returns clean markdown/html/text. It immediately frames the tool as the go-to for reading any web page, which separates it from the interactive session_* siblings and download/search.

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?

Provides an explicit when-to-use directive: 'Use whenever the agent needs to READ any web page' and lists concrete target types (blogs, docs, articles, JS-rendered SPAs, Cloudflare-protected sites). It doesn't name alternative sibling tools or spell out when-not-to-use, but the 'READ' scope is a clear boundary against interactive session tools.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety is covered. The description adds meaningful behavioral context: aggregation across engines, deduplication, optional full-content fetching, and image search returning direct URLs. This goes beyond the structured annotation without contradicting it.

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 three focused sentences with no filler. It front-loads the core function, then gives a usage cue, then adds distinguishing features. Every sentence earns its place.

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

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

For a search tool with 100% schema coverage and a read-only annotation, the description is sufficiently complete. It covers engines, dedup, content fetching, and image search. It does not detail the result format or paging behavior, but the schema and output context make that less critical.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds context like 'full content' and 'direct image URLs' but does not explain specific parameter syntax or value formats beyond what the schema provides, matching the baseline.

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

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

The description clearly states the tool searches the web across multiple named engines with aggregation and deduplication, distinguishing it from sibling browser/fetch tools. It also mentions optional content fetching and image search, making the purpose specific and 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?

The description explicitly says to use it when the agent needs to find information online and positions it as a search API replacement. It does not explicitly mention when not to use it or compare it to alternatives like fetch, so it misses the top tier for exclusions.

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

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

Annotations provide only a title, so no read-only/destructive hints exist and the description must carry that burden. The description discloses that a click occurs, but not side effects such as navigation, JavaScript execution, or page changes, nor error behavior for invalid or non-interactive indices, nor return value. This is minimal beyond stating the intended action.

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

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

The description is a single eleven-word sentence with no filler, front-loading the verb and object. It is appropriately sized for a simple 2-parameter tool and every word earns its place.

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

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

For a 2-parameter click tool with no output schema, the core invocation information is present: what to click and where the index comes from. However, the absence of behavioral notes such as side effects, error behavior, or return value, plus the lack of usage boundaries, makes it only minimally complete. The schema covers inputs well, but context around expected behavior remains thin.

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?

Both parameters are already described in the schema (100% coverage), so the baseline is 3. The description only adds a contextual link to session_state output for index, which the schema already expresses as '/state output', and gives no additional meaning for session_id. No parameter semantics beyond the schema are provided.

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 ('Click') and resource ('interactive element') and adds the index-based selection mechanism sourced from session_state output. This distinguishes it from the generic sibling 'click' by tying the action to a session-state index. Minor inconsistency: schema says '/state output' while description says 'session_state output,' but the intent is clear.

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 phrase 'from session_state output' implies the prerequisite workflow of retrieving the state to obtain an index. However, there is no explicit guidance on when to choose this over alternatives like generic click, session_input, or session_eval, and no exclusion criteria. This is implied usage rather than explicit guidance.

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

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

Annotations only provide a title, no read-only or destructive hints. The description adds 'free its resources' but does not disclose what exactly is destroyed, whether it is reversible, or if it invalidates the session ID permanently. It also does not mention any side effects or errors.

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 a single, concise sentence that is front-loaded with the action. No wasted words, perfectly efficient.

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 absence of annotations, description carries full burden. The tool is simple but for a mutational operation like closing a session, it should disclose irreversibility, effects on child operations, or if it throws errors. There is no output schema, so description should hint at return value or success/failure behavior. It falls short.

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 only parameter session_id has a description 'Session ID' in the schema, and schema description coverage is 100%. The description does not add any extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (close) and the resource (browser session) and its purpose (free resources). It distinguishes from siblings like session_create and session_state. Could be 5 but does not explicitly mention what happens to the session (e.g., invalidates the session ID).

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 implies when to use it (when done with a session) but does not provide explicit guidelines or alternatives. It does not say when not to use it or mention related tools like session_navigate, session_create. Minimal viable guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read behavior is established. The description adds valuable behavioral context beyond that: the 500-entry ring buffer, newest-last ordering, and the fact it captures output from multiple execution paths. It does not discuss edge cases or retention timing, which keeps it from being a 5.

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

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

The description is three sentences with no wasted content: the first defines the operation and output contract, the second adds buffer capacity and scope, and the third gives a concrete use-case. It is front-loaded and every sentence earns its place.

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

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

For a one-parameter read-only tool with no output schema, the description adequately covers what an agent needs: the output object shape, ordering, buffer size, and which actions are captured. The parameter is fully documented by the schema, and the annotation covers safety. No critical calling context 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?

Parameter schema coverage is 100%, and the only parameter is session_id, already documented as 'Session ID'. The description confirms the output is session-related but does not add any new semantic meaning about the parameter itself. This is the baseline 3 case where the schema carries the parameter-documentation burden.

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

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

The description states a specific read operation with a clear resource: it reads the session's recent page console output and lists the exact output shape. It makes the console-read domain clear, and the capture coverage across scripts, clicks, evals, and navigation helps distinguish it from sibling tools. It does not explicitly name or contrast any sibling tool, so it misses the top score for explicit differentiation.

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

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

The final sentence gives an explicit use case: call this to see why a page misbehaves. It also implies broad applicability by saying the output comes from page scripts, clicks, evals, and navigation alike. No alternatives or 'when not to use' guidance are provided, so it stops short of a 5.

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

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

The readOnlyHint annotation already indicates the tool is non-destructive, and the description does not contradict this. It adds context about the output format and the round-trip behavior with session_create, which clarifies what the tool does without side effects.

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 concise, consisting of two sentences that convey all necessary information without redundancy. It is well-structured and easy to parse.

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

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

For a simple read-only tool, the description is complete: it explains what the tool returns, why it would be used, and how it integrates with session_create. No additional context seems necessary for correct usage.

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 schema provides a minimal description ('Session ID') for the single parameter. The tool description does not elaborate on what constitutes a session ID or how it is used, but the parameter is straightforward and the schema covers it fully. Additional context could improve clarity, but it is not critical.

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's function: exporting cookies as a list of 'name=value' strings. It also specifies the purpose (persisting a logged-in session) and mentions round-tripping with session_create, making the intent 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?

The description provides explicit usage guidance: 'Use to persist a logged-in session and replay it later via session_create with cookies.' It explains when to use the tool, though it does not mention alternative tools. This is sufficient for a read-only utility.

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 meaningful behavior annotations besides a title, the description carries the transparency burden. It discloses that the session is persistent and interactive, survives page transitions, returns a session_id, and has an 8-minute idle timeout. It could also mention cleanup via session_close, but the key lifecycle behavior is disclosed.

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 with no filler: the purpose is front-loaded, the use-case guidance comes second, and the essential return value plus lifecycle detail is last. Every sentence earns its place.

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

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

For a tool with five optional parameters, no output schema, and no behavioral annotations, the description covers the essential contract: it returns a session_id and persists 8 minutes idle. It does fully explain the relationship with subsequent session_* tools, but the sibling list makes that inferable, and the description is otherwise sufficient for safe invocation.

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

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

Schema description coverage is 100%, and each parameter already has a rich description in the schema, so the baseline is 3. The tool description does not add meaningful parameter-level semantics beyond noting the idle persistence, which mostly mirrors the ttl_secs default and clamp already documented in the schema.

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

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

The description states a specific verb and resource ('Create a persistent interactive browser session'), then enumerates concrete capabilities (clicking, typing, scrolling, reading state across page transitions). It clearly distinguishes the tool from sibling session_* commands by framing it as the stateful entry point for interactive workflows.

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 when-to-use context ('login flows, forms, pagination, click-through') and excludes the one-shot read case ('rather than read it once'). It does not name a specific sibling alternative such as fetch, so an agent must infer the exact alternative, but the guidance is otherwise 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?

Annotations contain only a title, so the description carries the full burden of behavioral disclosure. It states that arbitrary JavaScript runs and returns a result, but it does not disclose side effects, security risks, error behavior, async/promise handling, or the scope of the execution context. For a potentially powerful eval tool, this is insufficient.

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 a single, front-loaded sentence with no filler or redundant information. Every word contributes to the core meaning.

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?

The tool is high-risk because it executes arbitrary JavaScript, and there is no output schema or behavioral annotations to fill gaps. The description covers the basic action and return value, but omits important context such as return serialization, error handling, and side-effect caveats. It is minimally viable but thin for such a powerful tool.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description adds no extra semantic detail beyond what the schema provides, but the baseline of 3 is appropriate because no compensation is needed.

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 action ('execute arbitrary JavaScript') against a specific resource ('the browser session') and mentions the result. This distinguishes it from sibling session_* tools, though it does not explicitly contrast it with the similarly named 'eval' sibling.

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

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

There is no guidance on when to use session_eval versus sibling tools like eval, nor any mention of prerequisites, exclusions, or context where this tool is appropriate. An agent would have to infer usage from the name and 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?

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: the bash format replays actions against a fresh session on the same server, the jsonl format returns a raw log, and the result is token-free when handed to a shell or cron. This goes well beyond what annotations alone 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 two focused sentences with no filler. It front-loads the core purpose and format names, then adds relevant detail about usage and output. Every clause earns its place.

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

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

For a tool with only two parameters, no output schema, and a read-only annotation, this description fully covers the purpose, both formats, default behavior, and expected output. An agent has everything needed 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?

The schema already covers both parameters with detailed descriptions, so the baseline is 3. The description adds extra meaning by enumerating the replayed action types (navigate/click/input/scroll/eval), clarifying the default behavior, and emphasizing the zero-token use case, which helps an agent understand the practical impact of the format 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?

The description uses a specific verb ('Export') and names a concrete resource ('a browser session's recorded action log'). It clearly differentiates this from sibling tools by focusing on exporting the action log rather than performing or managing session actions.

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

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

The description clearly explains the two output formats and their intended use cases (runnable replay script vs. raw JSONL log), giving an agent enough context to call it appropriately. It does not explicitly name alternatives or state when not to use it, but the use case is specific and 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?

Annotations provide no behavioral hints (no readOnly/destructive flags), so the description carries the full burden. It states that the tool types text, implying a write operation, but does not disclose side effects (e.g., overwriting existing text) or any prerequisites like session activity. This is minimal but not misleading.

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

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

A single sentence, front-loaded with the verb and target, and includes the key usage note about the index source. No redundancy or unnecessary detail—every word earns its place.

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

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

For a simple text-entry tool with three fully described parameters and no output schema, the description provides adequate context to use the tool correctly. It explains what it does and where to get the index, though it omits potential error scenarios or behavior when the element is not found. Overall, sufficient for the tool's complexity.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds value by clarifying that the index refers to elements from session_state output and that the target is specifically an input/textarea element—details not present in the schema. This enriches the parameter understanding.

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 action ('Type text') and the target resource ('input/textarea element'), with a specific scoping mechanism ('by its index'). It distinguishes itself from sibling tools like click, eval, and fetch by explicitly indicating text entry.

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 provides useful context on how to obtain the index: it must come from session_state output. This implicitly tells the agent to retrieve the index via the session_state tool first. No alternatives or exclusions are mentioned, but the context is clear enough for this tool's purpose.

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

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

Annotations only declare readOnlyHint=true, so the description adds meaningful behavior: sessions are live, include idle age, have an auto-eviction timer, and the idle timeout is 8 minutes. This goes beyond the annotation and helps the agent understand the tool's read-only discovery nature.

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

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

Two compact sentences with no filler. The core function is front-loaded, and the usage guidance and expiration policy are conveyed efficiently.

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

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

For a parameterless listing tool with no output schema, the description is complete: it names what will be returned (live sessions with idle age and time before eviction), explains the intended use case, and provides the key operational detail (8-minute idle expiry). An agent can call this tool correctly with no further information.

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 baseline is 4 per the rubric. The description doesn't need to explain parameter meaning since there are none, and it doesn't introduce confusion about inputs.

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

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

The description uses a specific action verb ('List') with a clear resource ('live browser sessions') and specifies the returned details (idle age, time before auto-eviction). It distinguishes itself from siblings like session_state and session_create by scoping to a collection-level discovery operation.

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 states when to use the tool ('to discover a session to reuse instead of creating a new one') and gives a concrete behavioral context (sessions expire after 8 min idle). This clearly routes the agent away from session_create and toward this listing tool.

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

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

Annotations contain only a title, so the description carries the full burden of behavioral disclosure. It only states the action without mentioning side effects, load/wait behavior, error conditions, or whether the prior page state is lost.

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 a single, front-loaded sentence with no filler. Every word is necessary and it is appropriately sized for a simple navigation tool.

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

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

Despite the tool's simplicity, the description is sparse given there is no output schema and no meaningful annotations. It provides the core action but omits return behavior, failure modes, and any session-lifecycle caveats that an agent would need for robust use.

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 documents both parameters with 100% coverage, so the baseline is 3. The description adds no additional meaning beyond what 'URL to navigate to' and 'Session ID' already 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?

The description uses a specific verb ('navigate') with a clear resource ('browser session') and object ('new URL'). This distinguishes it from sibling session tools like session_state or session_eval, which perform different actions.

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

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

The description provides no guidance on when to use this tool versus alternatives such as click or session_eval, which can also affect page state. It also does not mention prerequisites like requiring an existing session.

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?

Despite readOnlyHint being the only annotation, the description discloses substantial runtime behavior: via="network" are confirmed requests, via="dom" are un-fetched candidates, iframes are kind "iframe" and should be navigated into, and the default output is compact rows. This goes far beyond the annotation and tells the agent exactly what to expect.

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 each sentence carries operational value. It is fairly long and largely duplicates the filter schema's wording, which keeps it from earning a 5.

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

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

There is no output schema, so the description carries the burden of explaining return shape, and it does: compact rows with method/url/status/type/size plus via tags. It also covers the prerequisite navigation step and the iframe follow-up action, so an agent has enough context to use 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?

Schema description coverage is 100%, so the baseline is 3. The tool description's filter semantics mirror what the schema already documents; it adds no new parameter-level meaning. The session_id parameter remains only 'Session ID' in both places.

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

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

The description opens with a specific verb and resource: 'Read the session's network request log.' It then clearly details the two modes (default rows and filter="media") and distinguishes network-confirmed entries from DOM candidates. This makes the tool's purpose unmistakable and unique among the session_* 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?

It explicitly says to navigate to the video page, let it load, then call, and explains when filter="media" is the reliable choice because HTML-embedded links are often decoys. It doesn't name sibling tools as alternatives or state an explicit when-not-to-use, but the context is otherwise 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?

Annotations are minimal (only title), so the description must carry the behavioral burden. It adds useful details like the built-in renderer, inclusion of DOM mutations, and the return structure. However, it does not explicitly state that the operation is non-destructive or describe error behaviors (e.g., missing selector). The read-only nature is implied but not declared.

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 filler. The core purpose and key return fields are front-loaded, and the pairing with session_viewport is an efficient addition. Every sentence earns its place.

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

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

The description covers the primary use case, return format, and default behavior. It omits detailed guidance on selector and full_page usage, but these are well-documented in the schema. Since there is no output schema, listing the return fields is helpful. The tool is sufficiently complete for correct invocation.

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 all parameters have descriptions. The description adds marginal value by reiterating the default viewport behavior and suggesting the pairing with session_viewport, but it does not introduce new semantics for parameters like selector or full_page 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?

The description clearly states the tool captures a screenshot of the session's current DOM state as a base64 PNG, explicitly distinguishing it from other session tools like session_state or session_viewport. The phrase 'mutations from clicks/evals included' adds specificity about what is captured, leaving no ambiguity about the tool's function.

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 provides a concrete usage context by noting that session_viewport + session_screenshot together show the responsive layout, implying when to use it for visual verification. However, it does not explicitly state when not to use it or mention alternatives, though no other screenshot tool exists among 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 only provide a title, so the description carries the behavioral burden. It discloses the core behavior and units, but does not mention side effects, session requirements, relative scrolling behavior, or what happens on invalid input.

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 a single, front-loaded sentence with no filler. Every word contributes to the meaning, and it remains highly scannable for an agent.

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

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

For a simple scroll tool with full schema coverage, the description covers the essential operation. It does not describe return values or explicitly state that the scroll applies to the session associated with session_id, but the low complexity and rich schema make this acceptable.

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 has 100% parameter coverage, including descriptions for amount, direction, and session_id. The description adds no new parameter semantics beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Scroll the page up or down') and the resource/scope ('by a number of viewport-heights'). This is specific enough to distinguish session_scroll from sibling tools like session_navigate, session_click, or session_input.

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 provides no guidance on when to use this tool versus alternatives, no prerequisites such as requiring an active session, and no exclusions. It only describes the operation itself, leaving usage decisions entirely to the agent.

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

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

Annotations already indicate readOnlyHint: true, and the description adds behavioral detail about the return format: 'compact text with [N] indexes.' It does not contradict the annotation and gives useful context beyond the safety hint.

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

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

Two short sentences front-load the core purpose and immediately specify the output format and downstream use. No filler or repetition exists.

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-only tool with no output schema, the description is complete: it explains what is returned, in what form, and how it connects to click/input tools. No important gap stands out.

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% for the single session_id parameter, so the schema carries the semantic weight. The description itself does not add parameter-specific detail, matching the baseline for high schema coverage.

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 ('Get') and resource ('current page state'), and adds the distinguishing detail that it returns an indexed list of interactive elements. It is clearly distinct from click/input tools because it frames them as consumers of the [N] indexes.

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 provides clear context by stating the output is 'for use with click/input tools', signaling that it is a prerequisite for those actions. It does not explicitly list excluded alternatives like session_eval or fetch, so it stops short of a full when/when-not explanation.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that, adding behavioral context about capturing localStorage as a complement to cookies. It explains the output shape and the practical benefit, going beyond the annotation without contradicting it.

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 zero redundancy: the first states the action and output format, the second gives the use case and timing. It is front-loaded with the core action and every sentence earns its place.

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

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

For a tool with one parameter and no output schema, this description is fully sufficient: it explains what it does, the output shape, how to use the result, and when to call it. No critical information for an agent to decide and invoke it is missing.

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

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

The single parameter session_id is fully documented in the schema (100% coverage), and the description adds no extra meaning beyond its obvious purpose. This matches the baseline for high schema coverage, where the description need not elaborate.

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 verb 'Snapshot' and the resource 'localStorage/sessionStorage' for the current origin, with an explicit output structure. It distinguishes this from cookies by noting it captures 'the half of login state that cookies can't carry', making the tool's unique role unambiguous.

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

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

It gives precise when-to-use guidance: feed the output back via session_create's storage field to restore logged-in state, and call before the session idles out. It also implicitly contrasts with cookie-based state, providing context for when this tool is relevant.

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

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

Annotations only carry a title, so the description carries the disclosure burden. It explains the side effects of setting the viewport: script-visible dimensions change, media queries re-evaluate, element rects re-anchor, and mobile mode alters pointer/hover matchMedia answers. It also documents the omitted-width/height retention behavior, which is useful and not visible from annotations alone.

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

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

The description is extremely dense and front-loaded, using two sentences to convey the operation, its observable effects, the special device-emulation flag behavior, and the default retention semantics. Every clause earns its place with no filler.

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

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

Given the simple primitive-type parameters and the absence of an output schema, the description explains what the tool does and what an agent should observe afterward. It does not elaborate on the return value or session lifetime implications, but the core facts needed to invoke it correctly are present.

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 schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds value by explaining the runtime consequence of these parameters: width/height drive script-visible layout and media query re-evaluation, while mobile=true changes pointer/hover and touch reporting. That goes beyond restating the schema.

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

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

The description opens with a specific verb-resource pair ('Set the session's viewport') and immediately clarifies the purpose as device emulation. It also lists concrete observable consequences (innerWidth/innerHeight, media queries, element rects), making the tool's role unmistakable and distinct from its sibling 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?

The description frames the tool as the way to apply device emulation to a session, with concrete examples of when the effect matters. It does not name explicit alternatives or exclusions, but no sibling tool competes for this responsibility, so the guidance is sufficient.

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 reveals critical behavioral traits beyond the readOnlyHint annotation: the event loop keeps running while waiting (so async operations progress), it returns a structured result (matched, elapsed_ms, detail), and it errors with a descriptive timeout message that names the selector/predicate. This is valuable because the output schema is absent and the agent needs to know what to expect on both success and failure.

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—three sentences—and each sentence serves a distinct purpose: what it does, why it's useful (with a concrete example), and what it returns/errors on. It is front-loaded with the core definition and wastes no words. The structure makes it easy to scan and parse.

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 that there is no output schema, the description fully covers the return shape and error format. It also explains the exclusivity constraint and provides a practical usage pattern. The tool's complexity (two mutually exclusive wait conditions, timeout semantics) is fully addressed, 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?

Although the input schema already describes all four parameters (100% coverage), the description adds meaning by stating the exclusivity constraint ('Exactly one of selector/predicate') and explaining that the predicate is polled until truthy and its value is returned. This goes beyond the schema's basic field descriptions, so it earns above the baseline of 3 for full schema coverage.

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 and resource: 'Wait until a CSS selector matches or a JS predicate turns truthy, with a timeout.' It also gives a concrete usage pattern ('navigate, session_wait for .price-card, then click/read') that distinguishes it from other session tools like click or eval. The tool's role as a waiting primitive is unambiguous.

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

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

It explicitly positions the tool as a replacement for 'blind sleeps for async content' and provides a step-by-step usage pattern. It also states the exclusivity constraint ('Exactly one of selector/predicate') and error behavior on timeout. This gives an agent clear guidance on when and how to use it without needing to infer from sibling tools.

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