zenpilot

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

With no annotations, the description carries the full burden, and it does disclose two useful traits: this is a real side-effecting mouse event, and the response reports page diffs with + lines (new controls get refs) and - lines. It omits whether the call waits for navigation/load, how failures surface, and whether existing refs stay valid after the click.

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

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

Two short sentences; the primary action and its mechanism are front-loaded, with the return-value note following. No filler, though the diff notation could be tightened slightly.

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

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

For a one-parameter, no-output-schema tool this covers the essentials: what to pass, where it comes from, and what the textual result looks like. Only failure/error behavior and post-click ref validity are missing.

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

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

Schema coverage is 0%, so the single `ref` parameter is undocumented in the schema; the description partially compensates by naming its source (read_page) and noting that newly appeared controls receive new refs. It still never shows the shape of a ref or what happens with a stale one, so the compensation is only partial.

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

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

States a specific verb (click), the resource (an element identified by ref), and the mechanism (a real mouse event, not a synthetic dispatch). It also ties the ref to read_page, so an agent can tell this apart from type/select/scroll siblings. It stops short of explicitly naming those alternatives.

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?

"ref (from read_page)" gives an implicit prerequisite: you must have called read_page first to obtain a ref. There is no explicit when-to-use/when-not, and no mention of what to do if the element isn't found or if a sibling like type or select would be more appropriate.

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

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

With no annotations provided, the description carries the full burden, but it only says 'Close a tab.' It does not disclose whether the close is destructive/permanent, whether unsaved state is lost, whether the tab must exist, or what happens on invalid tab_id.

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 short, front-loaded sentence with no waste, but its brevity reflects under-specification rather than disciplined concision.

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 mutation-with-no-annotations tool, the description is too thin: it omits tab_id sourcing, destructiveness, and error behavior, leaving the agent without enough to call it reliably.

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

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

Schema description coverage is 0% for the single tab_id parameter, and the description adds nothing about its format or where to obtain it (e.g., from list_tabs). It fails to compensate for the coverage gap.

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

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

States a specific verb (close) and resource (tab), so an agent understands this removes an existing browser tab. It implicitly contrasts with new_tab and switch_tab but does not name any sibling to differentiate scope.

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 on when to close vs. switch or navigate away, no exclusions, and no mention of any precondition. The agent must infer all usage context from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses a content-selection heuristic (prefers <main>/single <article>), but omits fallback behavior, truncation via max_chars, and tab targeting.

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 front-loaded sentence with zero filler. It is appropriately sized for a simple extraction 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?

Given two undocumented parameters, no annotations, and no output schema, the one-sentence description is too thin. It does not cover parameter behavior or expected return shape.

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

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

Schema description coverage is 0%. Neither tab_id nor max_chars is explained in the description, leaving the agent to guess whether tab_id defaults to the active tab and how max_chars truncates the output.

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 what it returns: readable main text, with an extraction preference for <main> or a single <article>. This distinguishes it from broader siblings like read_page, though it does not explicitly name alternatives.

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 on when to use this tool versus read_page, screenshot, or scroll. There are no prerequisites, exclusions, or alternative-routing hints.

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

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

No annotations, so the description carries the full burden, and it does add real behavioral context: the output format (ids, active tab marked with *), and the lifetime guarantee that a tab keeps its id while open. It stops short of saying whether anything is mutated or what the pagination/ordering is, but for a read-only listing that's minor.

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 tight sentences, front-loaded with the purpose, and each subsequent sentence adds a distinct, useful fact (active marker, id stability). Nothing wasted.

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

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

For a zero-param read tool with no output schema, the description covers the essentials of the return shape and id semantics. It could be richer (ordering, what happens with zero tabs), but nothing critical 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?

Zero parameters, so there is nothing for the description to clarify beyond the schema; baseline applies.

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

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

Specific verb+resource: 'List open tabs with ids' tells the agent exactly what comes back. It doesn't explicitly name siblings like switch_tab or close_tab, but the list-vs-manipulate distinction is obvious from the sibling names.

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 explicit statement of when to call it or what to do with the result, though the implied use — discover tab ids before switch_tab/close_tab — is easy to infer from the mention of ids. No exclusions or alternatives named.

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

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

With no annotations, the description carries the full burden. It usefully discloses one non-obvious trait — it waits for the page to finish loading (synchronous/blocking behavior) — but omits error handling, whether existing tab content is replaced, and permission/auth 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?

A single efficient sentence with no waste and the core action front-loaded. It is appropriately sized, though it could carry one more clause without becoming bloated.

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-param tool with no annotations and no output schema, the description covers the essential action and the load-waiting behavior, but leaves the tab_id semantics and failure modes unexplained. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It implicitly covers 'url', but says nothing about 'tab_id' (nullable, default null) — e.g., what happens when tab_id is omitted, whether a new tab is created or the current one is used.

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: 'Load url in a tab'. However, it does not distinguish itself from siblings like read_page, new_tab, or switch_tab, which also concern tab/page context, so an agent gets limited routing help.

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 explicit when-to-use or when-not-to-use guidance. It doesn't clarify the relationship between navigate and new_tab/read_page, leaving the agent to infer when navigation is the correct choice.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful side effect: the new tab 'becomes active' (a focus change). It does not say whether the previous tab's state is preserved, whether the response yields a tab identifier, or anything about popup-blocking/permission behavior.

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

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

A single front-loaded sentence with zero wasted words; the activation behavior is called out inline rather than buried.

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

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

For a one-parameter tool with no annotations and no output schema, the description is adequate but thin: it does not indicate what the call returns (e.g., an identifier usable with switch_tab/close_tab), which is the main missing piece for correct follow-up actions.

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

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

Schema description coverage is 0%, so the description must compensate. 'Optionally loading url' correctly conveys that url is optional and what it does, but adds nothing about accepted format (absolute vs relative) or what loads when it is omitted.

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?

Specific verb+resource: 'Open a new tab' is unambiguous and clearly distinct from the siblings switch_tab, list_tabs, and close_tab, which deal with existing tabs. It stops short of naming or contrasting those siblings explicitly, so it lands at 4 rather than 5.

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

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

There is no guidance on when to open a new tab versus using switch_tab to reuse an existing one, or versus navigate. The use case is only implied by the verb; no prerequisites or exclusions are given.

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

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

With no annotations, the description carries the full burden and does an unusually good job: it discloses ref expiry rules, that dropdown options are truncated to the first few (select can still reach any), how checked state and 'clickable' custom toggles are represented, and that newly created controls count against the current read. Gaps: nothing about which tab is read by default, response size limits, 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?

It is front-loaded with the return semantics, which is correct, and has little padding. But the final sentence ('Refs that click, type and select give for new controls count as this read_page's') is garbled and hard to parse, and the dropdown/clickable notes are ordered awkwardly.

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 and no annotations, the description must explain the return shape, and it largely does—element outline, ref format, state markers, truncation. The missing piece is tab targeting: the only parameter's default behavior is undocumented, leaving an ambiguity an agent will hit immediately with multiple tabs open.

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 tab_id has 0% schema description coverage, and the description never mentions it. An agent cannot tell from either source whether omitting tab_id reads the active tab or defaults to something else, which matters in a multi-tab workflow with list_tabs/switch_tab siblings.

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

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

The description makes clear what the tool returns: an outline of visible interactive elements plus text, with refs (r12) used by click, type and select. That implicitly separates it from the action siblings. It does not, however, distinguish it from get_text, which is the nearest ambiguous sibling for 'read page content'.

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

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

Usage is only implied: refs come from this tool and expire when you call it again or navigate, so an agent can infer it must call read_page before click/type/select. There is no explicit when-to-use statement and no exclusion or comparison against get_text or screenshot.

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

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

With no annotations, the description carries the full burden and does so: it discloses the side effect (saved to the user's Mac), the downstream audience (developer review, filed as a GitHub issue), and an explicit privacy constraint to omit personal data and anything the user typed. That is exactly the context an agent needs before emitting a report.

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

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

Front-loads the core action, then usage conditions, then per-field guidance, with no filler sentences. The parenthetical example list is dense but each example maps to a distinct failure mode; slightly more compact phrasing would make it 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?

A three-parameter, non-mutating feedback tool with no output schema needs exactly what is given: trigger conditions, field-level expectations, an example goal, and data-handling rules. Nothing an agent needs in order to file a usable report is missing.

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

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

Schema coverage is 0%, so the description must compensate — and it defines all three fields: goal ("in a few words" plus a worked example), problem ("what you tried and what happened, naming the elements, refs' roles and errors"), and workaround ("what worked instead, if anything"). This adds real guidance the bare schema titles do not.

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

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

Opens with a specific verb and addressee: "Tell the zenpilot developers about something you couldn't do in Zen with these tools." This unambiguously separates it from every sibling (click, type, read_page, etc.), which are browser actions rather than a feedback channel.

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 scopes the trigger condition ("when a task needs something the tools lack... or only works after a workaround") and gives concrete examples: drag and drop, click-ignoring widgets, typing/select failures, content read_page misses. It also states a calling cadence ("once per problem"), leaving little to infer.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'Visible part' usefully signals that off-screen content is excluded, but nothing is said about the return format (image data vs. path), permissions, or 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?

A single short sentence with no waste and the key scoping qualifier ('visible part') front-loaded. Its brevity, however, tips into under-specification rather than disciplined conciseness.

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 annotations, no output schema, and an undocumented parameter, the description is too thin for an agent to call this confidently—especially since the return format of a screenshot tool is a critical unknown.

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?

One parameter (tab_id) with 0% schema description coverage and a null default. The description never mentions tab_id or explains what happens when it is omitted (e.g., capturing the active tab), so it does not compensate for the schema gap.

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

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

The phrase 'Screenshot of the visible part of a tab' identifies the resource (a screenshot) and the scope (visible viewport of a tab), which distinguishes it from read_page/get_text. However, it's a noun phrase with no verb and no explicit statement of what the tool does (capture/return an image), leaving the action implied rather than stated.

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

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

There is no guidance on when to use this tool versus siblings like read_page, get_text, or scroll. The word 'visible' hints at a viewport-only scope but never says to scroll first or when a screenshot beats text extraction.

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

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

With no annotations, the description carries the full behavioral burden, yet it only names the input gesture (mouse wheel) and unit. It does not say which tab is affected when tab_id is null, whether the page must be focused, or whether scrolling is relative or absolute.

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 waste-free sentence, front-loaded with the action and unit. It is appropriately sized but too terse to cover the parameters the tool exposes.

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

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

For a 3-parameter tool with zero annotation coverage, no output schema, and 0% schema description coverage, the description is inadequate: direction and tab targeting are never addressed, so an agent cannot reliably call it.

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

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

Schema description coverage is 0%, so the description must compensate. It explains only 'amount' (in pixels), leaving the direction enum (up/down/left/right) and tab_id entirely undocumented in both the schema and the description.

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

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

States a specific verb (scroll), resource (the page), and mechanism (mouse wheel) with a unit (pixels). It is clearly distinct from all siblings, none of which scroll, but it omits the direction dimension that the tool actually supports.

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 this versus alternatives (e.g. read_page/get_text to inspect content) or any prerequisite such as needing an active tab. An agent must infer the usage context entirely.

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

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

With no annotations, the description carries the full burden and does well: it discloses the open/filter/click/verify sequence and the option-matching heuristic. It omits what happens on no match, errors, or whether the operation is reversible.

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

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

Front-loaded with the purpose, then efficiently details behavior and outcome. Every sentence adds useful information with no wasted wording.

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

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

For a two-parameter action with no output schema or annotations, the description is nearly complete: it covers the selection flow, matching semantics, verification, and page-change reporting. Missing failure-mode behavior and ref sourcing are the main remaining gaps.

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

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

Schema coverage is 0%, so the description must compensate. It explains option matching well (exact text, or the only one starting with or containing it) but only says 'by ref' for ref, without defining its format or how to obtain it.

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: choose an option in a dropdown/select/combobox/listbox. The behavior is clearly distinct from generic click/type siblings because it explains opening, filtering, selecting, and verifying the choice.

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

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

Gives clear context for when to use it: any dropdown, combobox, or listbox selection, with matching behavior described. It does not explicitly say when to use click or type instead, so it falls short of full alternative routing.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about what happens if tab_id is invalid, whether the previously active tab is affected, or whether this changes OS/browser focus. It conveys only the surface mutation of active state.

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

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

One short, front-loaded sentence with no filler; sized appropriately for a simple single-parameter tool. It is arguably too terse given the semantic gaps elsewhere, but there is no wasted 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?

For a simple one-parameter action tool with no annotations and no output schema, the description still omits the essential detail of tab_id format and error/edge-case behavior. An agent can guess the intent but not call it reliably.

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 required parameter tab_id has 0% schema description coverage, and the description provides no compensating detail—no indication whether tab_id is an index, an ID string, or a title, nor how to obtain one. This is a real gap the description should have filled.

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 clear verb-like action on a specific resource: activating a tab. An agent can distinguish this from list_tabs, new_tab, and close_tab by the 'make active' phrasing, but the description never names those siblings or explicitly contrasts with them.

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

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

There is no guidance on when to use this versus new_tab (create then focus) or list_tabs (discover a tab_id first), no prerequisites such as the tab needing to already exist, and no exclusions. Usage is left entirely to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the key-event mechanism, that newlines become Shift+Enter so chat messages aren't sent, that submit=true presses Enter, and that it reports page changes 'like click'. It leaves out what happens if the ref is stale/hidden or whether existing content is replaced destructively beyond the word 'replace'.

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

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

The core action and the sibling routing are front-loaded in the first two sentences, with format details after. The long enumeration of input-type formats is dense but each entry earns its place as disambiguation.

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

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

No output schema or annotations exist, yet the description covers mechanism, side effects, submission, return behavior in outline, and alternatives. The main remaining gap for a 3-parameter mutation tool is ref provenance and failure behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for 'text' (newline handling, per-input-type formats) and 'submit' (presses Enter after), but 'ref' is only mentioned as an opaque identifier with no explanation of where a ref comes from or how it is obtained.

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

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

States a specific verb, resource and mechanism: 'Replace the content of a field (by ref) with text using real key events.' It explicitly distinguishes itself from the sibling 'select' for dropdowns, so an agent can route correctly without opening the 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?

Names the alternative tool and the condition that selects it ('To choose from a dropdown, use select'), then adds per-input-type value formats to prevent misuse on date/time/color/range fields. It also explains the submit=true path for submitting after typing.

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

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

With no annotations, the description carries the full burden and does disclose real behavioral traits: absolute path semantics, a sandbox restriction tied to upload_dirs config, and that uploads are logged. It does not say whether the call waits for the upload to complete, what happens with an invalid or stale ref, or whether a change/submit event is fired on the 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?

Three short sentences, front-loaded with the action and semantics before the constraints. Minor waste in the line-broken 'paths are absolute...' sentence, but nothing extraneous.

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 mutation-style tool with no annotations and no output schema, the description covers inputs and security constraints well but leaves the agent guessing about completion semantics, error behavior, and how to acquire a valid ref. These are the gaps that matter most for calling it correctly the first time.

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

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

Schema description coverage is 0%, so the description must compensate, and it mostly does: 'ref' is identified as the file input target and 'paths' is defined as absolute file paths subject to an allow-list. It stops short of explaining how a ref is obtained (e.g. from read_page) or whether directories are permitted.

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 ('attach files to a file input') and clarifies the semantics with 'as if the user picked them', which is meaningfully different from the sibling click/type tools. It is clearly distinguishable from every sibling, though it does not explicitly name an alternative.

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 'attach files to a file input (by ref)' gives the agent a clear condition for when this tool applies rather than click/type. It also states the hard constraint that only files under directories listed in upload_dirs are allowed, but gives no guidance on failure cases or prerequisites such as obtaining a valid ref first.

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