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

The description adds real behavior beyond the annotations: a runtime permission ('optional browser permission enabled in the panel') gates the tool, and results are scope-limited ('unauthorized origins are hidden'). What it omits is what happens on a duplicate create, and it never acknowledges the mutation side of 'create' despite destructiveHint=true in the annotations.

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

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

Two sentences, zero filler, with the primary capability front-loaded before the constraint. Every clause carries information an agent needs.

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 low-parameter tool with no output schema, the definition covers purpose, permissions, and visibility scoping, but skips per-action required fields and says nothing about what a search returns or how results are ordered/limited. An agent could still mis-invoke create without a URL.

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 url, query, and title (75% coverage), so baseline is 3. The description goes beyond that by mapping parameters to actions implicitly: 'search' pairs with a text query, 'create' pairs with a URL. It does not state that url is conditionally required for create or whether title is optional there.

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

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

States two concrete verbs and the resource: 'Search bookmarks or create one for an authorized URL.' That is specific enough for an agent to distinguish it from firefox_history or firefox_downloads. It does not explicitly name the sibling it is not, so it stops short of a 5.

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

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

The two actions imply when to use each, and 'for an authorized URL' hints that create needs a URL. But there is no explicit guidance on when to use this versus firefox_history for browsing history, nor any statement about prerequisites or ordering. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is known. The description adds real value beyond them: it discloses that the click is gated by visibility/stability/obstruction checks and that the dispatched DOM event is synthetic, which affects how the agent should reason about side effects. It stops short of saying what happens when the element is stale or the check fails.

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

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

Two dense sentences with no filler, and the action and its preconditions are front-loaded before the risk warning. The phrase 'DOM input is synthetic' is terse to the point of ambiguity about what is synthetic (the event or the element reference).

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 destructive, non-idempotent interaction tool with no output schema, the description covers the main risk and the precondition checks, which is a reasonable baseline. It omits failure behavior, staleness of snapshotId, and tab/frame scoping, which matter 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 only 50%: ref and snapshotId are documented in the schema, but tabId and frameId have no description anywhere. The description text mentions no parameters at all, so it does not compensate for the gap, leaving the agent to infer which tab and frame context the click applies to.

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

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

The description names a specific verb and resource ('Click a current observed element') and adds the preconditions it enforces (visibility, stability, obstruction checks). It is clearly distinguishable from firefox_fill or firefox_select, though it never explicitly contrasts itself with the closest sibling, firefox_point.

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

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

It gives a caution that clicking 'may submit forms or cause external effects; follow the user intent,' which implies when to be careful rather than when to choose this over alternatives. There is no explicit routing guidance against siblings such as firefox_point (coordinate clicks) or firefox_fill, so the agent must infer the 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?

Adds substantial context beyond the annotations: required persistent read and debug permissions, a 15-minute or navigation-based expiry, the caveat that site instrumentation can be modified, worker exclusion, and a sensitive-data/untrusted-content warning. It does not explain why destructiveHint is true (presumably the clear action) or what read returns, but the disclosure is well above the annotation baseline.

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

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

Five short sentences, front-loaded with the core purpose and followed by constraints and safety caveats. Dense and free of filler, though the telegraphic style leaves some terms (e.g. 'persistent read and debug access') unexplained.

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

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

For a five-parameter, four-action tool with no output schema and no parameter documentation, the description is too thin. It omits action semantics, which parameters apply to which action, and what read returns, so an agent cannot reliably invoke anything but the default capture flow.

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% across five parameters, so the description carries the full burden and largely fails it. It never explains tabId, frameId, maxResults, or the levels filter, and it does not describe what start/read/clear/stop do or which parameters apply to which action. Only the loose phrase 'console messages and errors' hints at the levels enum.

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: 'Capture future document console messages and errors.' An agent can tell this is console capture rather than network or page reading. However, the tool is a four-action lifecycle tool (start/read/clear/stop) and the description only characterizes the capture phase, leaving the other actions unnamed.

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

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

There is no explicit when-to-use guidance and no comparison to siblings like firefox_inspect or firefox_network, which an agent could easily confuse with console capture. The only routing-adjacent information is the prerequisite 'persistent read and debug access' and the expiry rule, which are behavioral rather than selection 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, idempotentHint, non-destructiveness, and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious framing by labelling the returned content 'untrusted context' and tying it to an 'authorized' document, but it does not say what happens on unauthorized access or how frame-scoped reads behave, which is the main behavioral gap.

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

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

A single front-loaded sentence with no filler, and the returned fields are listed before the untrusted-context caveat. It is efficient, though the phrase 'the authorized document' front-loads an unexplained qualifier rather than the tab source.

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 0% parameter coverage, the description should at minimum explain the tab/frame selection and the authorization precondition. It lists the returned fields (URL, title, selected text) but leaves both parameters and the failure mode undocumented, making it only minimally sufficient for a two-parameter read 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?

Both parameters (tabId, frameId) have zero schema description coverage, so the description carries the full burden, yet it never mentions either parameter. An agent must infer that tabId selects the tab and frameId the subframe; nothing explains defaults, frame scoping, or whether frameId may be 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?

The description names a specific verb (Read) and enumerates the resource returned: the document's URL, title, and selected text. It is clear what the tool yields, but it does not distinguish itself from the sibling firefox_read_page, which an agent must otherwise disambiguate by opening both 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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to an alternative such as firefox_read_page or firefox_frames. The word 'authorized' hints that prior access must be granted, but the description never states that prerequisite or what to do when it is absent.

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

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

Beyond the annotations, the description discloses real behavioral traits: the 20 MiB size ceiling, the refusal to follow redirects, the required permissions ('site download and browser downloads'), and the guarantee that nothing is executed. The 'does not overwrite files' clause sits in tension with destructiveHint=true, but since the tool does write a new file to disk the write semantics are plausible rather than contradictory.

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 action and immediately followed by the constraints an agent needs to pre-check (size, redirects, permissions). No filler, though the permission sentence could be folded into the first to be even denser.

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

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

With no output schema, the description should say where the file lands and what the call returns, and it does not. For a write tool with a destructive hint, the agent is left guessing about the destination path and the success response, though the operational limits and permission prerequisites are well covered.

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 a middling 67%: url and filename are documented in the schema while saveAs carries no description anywhere. The description reinforces 'direct' for url and 'file name only' semantics for filename but adds no syntax or destination details, and saveAs remains undefined 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 names a specific verb and resource ('Download a direct authorized URL using GET') and pins the scope with concrete constraints, the 20 MiB cap and no redirects. It is clearly distinct from the plural sibling firefox_downloads (a listing tool), though it never states that contrast explicitly.

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

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

The qualifiers 'direct' and 'authorized' plus 'without following redirects' implicitly tell the agent this is for a single direct-file fetch, not a page fetch or a downloads listing. However, no explicit when-to-use vs firefox_downloads or firefox_upload guidance is given, and the consequences of a non-direct URL are left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the risk profile is supplied structurally. The description adds useful scope ('this extension', 'current session') but does not warn that cancel is irreversible, what happens to a paused download across sessions, or that operations target a single downloadId — context that would matter for a destructive tool.

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

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

A single, front-loaded sentence with no filler or redundancy. It is efficient, though its brevity comes at the cost of the parameter guidance noted elsewhere.

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, destructive, no-output-schema tool the description covers domain scope but omits the action semantics and the downloadId conditional. An agent could invoke it, but only by inferring behavior from the enum rather than from prose.

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% and the description mentions neither parameter. The action enum (list/pause/resume/cancel) and the conditional requirement of downloadId for all but 'list' go entirely undiscussed, leaving the description to add nothing beyond the raw schema.

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

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

States a specific verb pair (list/manage) and resource (downloads), and narrows scope to downloads 'initiated by this extension in the current session', which distinguishes it from the sibling firefox_download that starts downloads. It never names a sibling explicitly, but the domain boundary is inferable.

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?

Coverage of when to call it is only implied by the word 'manage' — there is no explicit guidance on which action to pick, nor any statement that downloadId is required for pause/resume/cancel but not for list. An agent must read the enum to discover that.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the write/overwrite nature is structured data. The description does add real value by saying input is dispatched as 'framework-compatible input events', implying framework state is updated rather than just the DOM value. However it never states that an existing field value is overwritten (the destructive behavior) or that the snapshotId must be current.

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 tight sentences with no filler, leading with what the tool does and following with the exclusion. Slightly cryptic phrasing ('their separate flows') costs a little clarity but nothing is wasted.

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

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

There is no output schema, and the description does not say what a successful fill returns, whether the value replaces or appends to existing content, or what happens on a stale snapshotId. For a destructive browser mutation with 40% schema coverage, those are meaningful omissions.

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 only 40%: only 'ref' and 'snapshotId' are documented, while 'tabId', 'value' and 'frameId' have no description anywhere. The tool description mentions no parameters at all, so it does not compensate for the three undocumented ones or clarify value length limits or frame scoping.

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?

Uses a specific verb ('Fill') and resource ('ordinary text field or editable region'), and distinguishes the scope from password, payment, auth-code and file inputs. It stops short of naming which sibling tool handles those excluded cases, so the routing is implied rather than explicit.

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

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

Explicitly excludes the cases where this tool must not be used (passwords, payment fields, authentication codes, files) and points to 'their separate flows'. The only gap is that it never names those alternative tools, so an agent must still guess which sibling to call.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the genuinely useful notion of "fresh references" (implying staleness of prior lookups), but says nothing about match ambiguity, whether hidden/offscreen elements are included, or what a reference looks like.

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 front-loaded sentence with zero filler and the result contract placed at the end where it belongs. It is arguably too sparse rather than padded, which is a completeness problem, not a conciseness one.

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, an open-world tool, and two of three parameters undocumented, the description should explain what a returned reference is and how to use it. Instead it stops at one sentence, leaving the agent to guess about tab/frame scoping and result 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 coverage is only 33%: only `text` is documented. The description says "by text" but never explains `tabId` (required) or `frameId`, and frame scoping matters given a firefox_frames sibling. It fails to compensate for the documented-parameter gap.

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

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

The description pairs a specific verb ("Find") with a specific resource ("observable elements by text") and states the output contract ("fresh references"), so an agent knows this is a DOM-query tool, not an action. It does not name or distinguish itself from potential siblings such as firefox_inspect or firefox_click, leaving overlap to inference.

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: the phrase "return fresh references" hints that this is a discovery step whose results feed a later action and that older references go stale. There is no explicit when-to-use, no exclusion of firefox_inspect, and no statement of prerequisites like an attached tab.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the non-obvious behavior that results are filtered by read access and that cross-origin frames are gated behind separate permissions — a real disclosure beyond the structured fields, though it omits what happens for an unauthorized tabId (error vs empty list).

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

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

Two short sentences with the scoping constraint front-loaded and no filler. The second sentence is a verbless fragment, but it stays readable and every clause carries information.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, most of the burden is met. Still missing: what identifies a frame in the result (so it can be passed to firefox_read_page or firefox_tab_action), whether the frame list is origin-filtered, and whether it includes the top frame.

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 required tabId, so the schema gives only a name and integer type. The description partially compensates by stating the tab must be "authorized," implying tabId must come from firefox_list_tabs, but it adds no format or provenance detail beyond that hint.

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?

"List frames" gives a specific verb and resource, and "in an authorized tab" scopes it. It does not name or distinguish itself from any sibling, but no sibling overlaps directly (tab-level tools like firefox_list_tabs operate at a different granularity), so the purpose is still 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?

"Cross-origin frames require their own permissions" implies the prerequisite path (firefox_request_access) and explains why a frame may be absent, which is genuine when-to-use context. However, the alternative is never named, and nothing says when not to call this versus firefox_list_tabs or firefox_read_page.

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

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

The annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description does add real value by disclosing the optional-permission gate and the fact that results are filtered to origins with read access. It says nothing about result volume, ordering, or what an empty or denied result looks like.

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

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

Two short sentences with no filler, and the permission precondition is front-loaded before the result-filtering note. The second sentence is slightly cryptic in isolation but not wasteful.

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

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

With no output schema, the description carries the burden of explaining the return shape, and 'only origins with read access' is only a partial hint. It also leaves maxResults undocumented and doesn't say how results are limited or ordered, but for a simple two-parameter search this is roughly the minimum viable level.

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 only 50%: 'query' is documented as 'Search text.' while 'maxResults' (integer, 1-100) has no description at all. The tool description adds no parameter meaning whatsoever, so the maxResults semantics are missing from both structured fields and prose.

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

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

The description gives a specific verb and resource: 'Search browser history'. That is clear enough to act on. However, it never distinguishes itself from the sibling firefox_tab_history, which is a plausible source of confusion for an agent picking between the two.

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

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

It states one precondition: the user must have enabled the optional permission. Beyond that, it offers no when-to-use guidance relative to siblings such as firefox_tab_history or firefox_bookmarks, and no guidance on what a query may contain or what to do when access is denied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds real value: the debug-access prerequisite, the explicit omission of field values and raw HTML, and the guarantee that supplied code is not executed. It stops short of describing failure behavior when the element or selector match is missing.

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 tight sentences: capability and addressing modes first, then constraints and exclusions. Every clause carries information an agent needs, with no redundant restatement of the schema or the annotations.

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

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

For a read-only inspection tool with no output schema, enumerating the three returned categories plus the debug-access requirement is close to sufficient. Marginal gaps remain around element-not-found behavior and whether frameId must accompany tabId for iframe inspection.

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 60%, so the description compensates for some of the gap by tying ref to the current snapshotId and presenting the selector as an alternative addressing mode. tabId and especially frameId carry no meaning beyond their bare types in either the schema or 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 ("inspect") with three concrete resources: element box, computed styles, and basic accessibility signals. It implicitly distinguishes itself from firefox_read_page by being element-scoped and from firefox_click/fill by being read-only, but it never names a sibling, so the differentiation is inferred rather than explicit.

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

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

Gives mode-selection guidance (use current snapshotId/ref or a unique CSS selector) and a prerequisite ("Requires debug access"), which is genuinely useful. However, it never states when to choose this over firefox_read_page or firefox_find, nor what to do when both a ref and a selector are available.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, but the description adds real context the annotations cannot: the events are synthetic and may be silently ignored by the page, and Enter can trigger form submission (which explains the destructive hint). It does not cover focus requirements or what happens if ref is stale, but the added behavioral value is substantial.

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 followed by the two caveats that matter. Nothing is redundant, though the extreme terseness leaves gaps that a slightly longer description could have filled.

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 5-parameter mutating interaction with no output schema, the description covers the key behavioral risks (synthetic events, form submission) but omits tab/frame targeting semantics and the requirement for a fresh read_page snapshot. Adequate to invoke safely in the common case, incomplete for multi-frame or stale-reference scenarios.

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 only 40% across 5 parameters; only ref and snapshotId carry descriptions, and the description adds no detail on tabId or frameId at all. "Supported key" merely restates the enum that is already in the schema, and "observed element" only loosely points at the read_page prerequisite. With below-50% coverage the description needed to compensate and does 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?

States a specific verb and resource ("Send a supported key to an observed element"), which clearly separates it from the mouse-driven firefox_click and the text-driven firefox_fill without needing to name them. It stops short of explicit sibling differentiation, e.g. no mention of when to prefer click or fill.

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 line "Enter can submit forms" gives an implied usage scenario and "may be ignored by the site" warns about a failure mode, so an agent can infer when this is appropriate. However, there is no explicit when-to-use/when-not-to-use statement and no routing to alternatives like firefox_click or firefox_fill for elements that do not accept keys.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the lower bar applies. The description does add real behavior beyond them: the result set is restricted to tabs with persistent read access and others are silently omitted. It does not explain how that access is obtained or whether the filtering is per-tab or per-session.

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, front-loaded sentences with no padding; the core action comes first and the filtering caveat follows. The only cost is that the terse phrasing leaves "persistent read access" undefined rather than using that space to clarify it.

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

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

With no output schema, the description should carry the shape of the return value, and it does not say what a listed tab contains or how access scope is represented. For a zero-parameter list tool this is adequate but not complete, since the agent cannot predict the response contents.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate in the input schema, and it correctly says nothing extraneous about arguments.

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

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

States a specific verb and resource ("List tabs") and adds a scope qualifier ("with persistent read access"). The second sentence clarifies that the result set is filtered rather than exhaustive, which helps distinguish it from tab-manipulation siblings like firefox_tab_action or firefox_tab_group, though the phrase "persistent read access" is not defined.

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: an agent can infer this is the enumeration call, and "Other tabs are hidden" hints that firefox_request_access may be needed for the rest. But no alternative or condition is named explicitly, and the description never tells the agent what to do when a needed tab is missing from the list.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the description should clarify which actions mutate page state; it instead lumps inspect together with play/pause/seek without saying inspect is a safe read. Nothing is said about whether play requires user-gesture/autoplay permissions, what happens if multiple media elements exist, or what inspect returns.

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

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

Two short sentences, front-loaded with the action list and followed by a scoping caveat; nothing is padding. It is perhaps too terse for the parameter surface it covers, but the wording itself is 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?

With 5 undocumented parameters, mutation-capable actions, and no output schema, the description leaves too much for the agent to infer: which element index is targeted, whether time is seconds, and what inspect returns (track list?). It is well short of what this tool's complexity requires.

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% across 5 parameters, so the description carries the full burden and largely fails. It implies the action enum and hints at seek, but never explains tabId, frameId, index (which media element?), or that time is the seek target and is required for seek.

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 set (inspect, play, pause, seek) against a specific resource (HTML5 media elements and text tracks), which is clearly distinct from nearby siblings such as firefox_inspect or firefox_screenshot. It doesn't explicitly contrast with siblings, but the resource is unambiguous.

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

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

The second sentence usefully scopes the tool to browser media elements rather than private video APIs, which implies when it will and won't work. However, there is no guidance on prerequisites (a tab actually playing media), on when to use inspect versus the mutating actions, or on alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is known. The description adds almost nothing beyond that: it never says the current page content and its in-page state are replaced, what "authorized" requires (presumably firefox_request_access), or what happens on a blocked or failed navigation.

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

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

It is a single front-loaded sentence with no filler clauses, which is structurally clean. However, the brevity is achieved by removing substance rather than by compressing it, so the terseness works against the definition instead of for it.

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

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

There is no output schema, and the tool is a destructive, open-world mutation acting on browser state, which raises the completeness bar. With only two parameters and a clear schema the core call is inferable, but the authorization model and the effect on existing page state remain undocumented.

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 50%: url is documented in the schema (HTTP/HTTPS, 1-2000 chars) while tabId has no description at all. The description does not compensate, offering only the circular claim that the tab must be "authorized" rather than explaining that tabId must come from firefox_list_tabs/open_tab and that the URL scheme is restricted.

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

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

The description names a verb ("Navigate") and an implicit resource (a tab, via "tabId"), but replaces the actual destination concept with the vague word "destination" and adds "authorized" twice without defining it. It gives no basis for distinguishing this from siblings like firefox_open_tab or firefox_tab_history, which also move a tab to a page.

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 when-to-use guidance, no mention of prerequisites for the "authorized" state, and no alternative named (open_tab for a new tab, tab_action or tab_history for other tab changes). The agent is left to infer the routing decision entirely from the tool name.

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

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

Goes beyond the annotations by disclosing the data scope, stating that cookies, headers, bodies and URL queries are omitted, which matters for privacy-sensitive consumers, and that collection requires persistent debug access. Annotations already flag destructiveHint=true and openWorldHint=true, and the description is consistent with them (clear/stop are the destructive operations). It does not describe the shape of what 'read' returns or whether start is per-tab or global.

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, dense sentences with the core capability front-loaded, the prerequisite next, and the exclusion last. Nothing is wasted, though the first sentence packs four actions and three attribute names into one clause, which is dense but still readable.

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 6 parameters, no output schema and 17% schema coverage, the definition leaves gaps: it never says what a 'read' returns (which fields per request), how the filters combine, what maxResults defaults to, or whether state is per-tab. It covers the prerequisites and privacy boundaries well, but not enough for an agent to predict results.

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

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

Schema description coverage is only 17%, with only the resource-type parameter documented, so the description must compensate and it only partially does: 'duration, status and filters' loosely maps to statusMin, errorsOnly and maxResults, and the four action verbs map to the action enum. tabId, maxResults limits and errorsOnly semantics are left entirely to the bare schema.

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

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

States specific verbs (start, read, clear, stop) against a specific resource (Firefox request metadata), and explicitly names the sibling firefox_performance as the alternative for resources not surfaced by webRequest. The phrase 'Firefox-visible request metadata' is slightly jargon-heavy, so it is not quite a perfect 5, but an agent can tell what this tool does and how it differs from neighbors.

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

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

Gives an explicit alternative and the condition that selects it ('Use performance for resources not reported by webRequest') plus a prerequisite ('Collection needs persistent debug access'). It does not explain when to choose read versus clear versus stop, but those are implied by the verbs and the action enum.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so the safety profile is covered. The description adds one genuinely new behavior: redirects to unauthorized origins are blocked. It does not explain what "authorized" means, how authorization is obtained, or why an open-tab action carries a destructive 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-loaded with the action and followed immediately by the constraint; no filler. It is perhaps overly terse given the undocumented second parameter, but nothing is wasted.

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

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

There is no output schema and no mention of what is returned (e.g., a tab identifier) for a tool whose output would be needed by sibling tools like firefox_release_tab or firefox_tab_action. The authorization prerequisite and the meaning of the `active` flag are also unaddressed, so this is only minimally complete for a two-parameter state-changing tool.

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

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

Schema coverage is only 50%: url is documented in the schema, but the boolean `active` parameter is undocumented in both schema and description. The description adds no meaning about what `active` controls (e.g., whether the new tab takes focus), so 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 and resource ("Open an authorized HTTP/HTTPS URL in a new tab") and adds a scope constraint. It implicitly distinguishes itself from firefox_navigate (existing tab) and firefox_tab_action, but never names an alternative, so differentiation is inferred 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?

"Open ... in a new tab" implies the use case versus navigating an existing tab, and "authorized" hints that a prior access grant (likely via firefox_request_access) is required. Neither the when-to-use condition nor the prerequisite step is stated explicitly, leaving the agent to infer both.

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 this a safe, idempotent read, so the description's real contribution is the data-quality disclosures: unauthorized origins are hidden, query/hash are stripped, and cross-origin timing may be restricted by Firefox. Those are non-obvious output characteristics an agent could otherwise misread as missing data. It stops short of describing the shape or ordering of results.

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

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

Four short sentences, each carrying distinct information: capability, precondition, redaction behavior, and platform limitation. The capability is front-loaded and no sentence is filler.

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

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

With no output schema, the description should indicate what comes back (entry lists per timing category) and it does not; nor does it cover the three undocumented parameters. The behavioral caveats it does include are valuable, but for a three-parameter tool with zero schema documentation the definition is only partially complete.

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

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

Schema description coverage is 0%, so the description carries the full burden for tabId, frameId and maxResults, yet none of them are mentioned. An agent gets no clue from prose that maxResults caps collection at 200 or that frameId scopes to a subframe, leaving all three parameters to be inferred from bare types.

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

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

The description names a specific verb ('Read') and concrete resource set ('native Navigation, Paint and Resource Timing'), which unambiguously places it in the Performance Timing API domain and separates it from siblings like firefox_network and firefox_console. It does not explicitly contrast itself with those siblings, which keeps it just below the top mark.

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?

'Requires debug access' is a genuine prerequisite that tells the agent a precondition exists before calling. However, there is no guidance on when to prefer this over firefox_network or firefox_console for timing questions, and no statement about when the tool is not 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: the screenshot is consumed and must be re-captured, and frames are not entered automatically. It omits what happens on a failed hit (error vs. silent no-op) and whether the action waits for load.

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 capability and followed by the two constraints that most affect correct use. No filler; slightly terse given the number of undocumented parameters, but nothing is wasted.

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

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

With five required parameters, 20% schema coverage and no output schema, the definition covers the core interaction model well but leaves tabId meaning and failure/return behavior unexplained. An agent could invoke it correctly in the happy path but would not know how errors surface or what the call returns.

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 only 20% (just screenshotId), so the description has to carry more weight. It does enumerate the action variants in prose and ties x/y to a screenshot's coordinate space, but tabId is undocumented in both places and the relationship between screenshotId and its producing tool is only hinted at ('recent screenshot').

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

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

Names the specific operations (click, double-click, hover, context menu) and the precise target (coordinates from a recent screenshot), which cleanly separates it from element-based siblings like firefox_click. It stops short of naming that sibling explicitly, so an agent must infer the distinction from 'at coordinates'.

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?

'Coordinates from a recent screenshot' plus 'capture again after changes' implies the intended workflow (screenshot → point → re-screenshot), and 'Does not enter frames automatically' rules out a case. However, no alternative tool is named and there is no explicit when-not guidance such as using firefox_click for element selectors.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, and the description adds meaningful context beyond that: it discloses shadow-root coverage, warns that page content is untrusted, notes that sensitive field values are omitted, and names the returned snapshotId and references. It falls short of a 5 because it does not explain truncation behavior or how maxChars affects the snapshot.

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

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

Four short sentences, front-loaded with the core action and followed by trust, security, and return-value notes. There is no wasted wording, and each sentence contributes useful information.

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

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

The description covers purpose, trust, sensitive-data handling, and return artifacts, which is helpful given the lack of an output schema. However, it leaves the input parameters undocumented and does not route the agent to alternatives or explain access prerequisites, which are significant gaps for a tool with three parameters and many browsing siblings.

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 carry the burden of explaining the three parameters, but it does not mention tabId, frameId, or maxChars at all. The phrase 'document or frame' loosely hints at frame targeting, but it gives no guidance on required tabId, frame selection, or character limits.

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: reads visible text and semantic element references from a document or frame, including open shadow roots. This is clear enough for an agent to understand the tool, though it does not explicitly differentiate it from siblings like firefox_inspect, firefox_find, or firefox_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?

The description implies usage by saying it returns references for actions, but it does not state when to use this tool versus firefox_inspect, firefox_find, firefox_screenshot, or firefox_context. No exclusions or prerequisites are given beyond the word 'authorized'.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds real value on top: it says exactly which capabilities are revoked (agent control, navigation protection), that debug collection stops, and that site permissions survive. It does not state whether the release is reversible or how to re-acquire control, which keeps it below 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?

One front-loaded sentence with three purposeful clauses, each conveying a distinct behavioral fact, plus a short preservation note. 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 single-parameter tool whose annotations already carry the destructive/idempotency profile and with no output schema to explain, the description covers the effects and the retained state well. The remaining gap is the undisclosed tabId semantics and what the call returns or errors on.

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% and the sole parameter tabId is never mentioned in the description, so no meaning is added beyond the bare 'integer, minimum 0'. It does not say where a tabId comes from (e.g., firefox_list_tabs) or what happens for an invalid or already-released id.

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

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

Names a specific verb ('release') and resource ('a tab'), and enumerates the concrete effects: ending agent control, ending navigation protection, and stopping debug collection. That is far more informative than a name restatement and differentiates it from lifecycle siblings like firefox_open_tab or firefox_tab_group, though it never names which sibling is the counterpart.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The clause 'Site permissions remain' implies a contrast with a more thorough teardown, but the agent must infer that, and nothing tells it when to prefer release over firefox_tab_action, firefox_tab_group, or re-requesting via firefox_request_access.

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 openWorldHint, non-idempotent, and destructiveHint, so the safety profile is partly structured. The description adds one genuinely new behavioral fact — the page-content trust boundary — but does not explain that the call blocks on a user prompt, that denial is a normal outcome, or why a request-only tool carries destructiveHint=true. Without that, an agent may hesitate to invoke 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 short sentences with no filler, and the core action is front-loaded. The second sentence is terse to the point of being cryptic, but it earns its place by establishing the trust boundary.

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

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

No output schema exists, so the description must cover outcomes, and it says nothing about approval persistence, scope of the grant, or denial handling. For a gate that sits in front of nearly every sibling tool, missing the linkage to those actions leaves the agent under-informed about when this definition applies.

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 67%, with url and reason already documented in the schema. The phrase 'exact origin' usefully constrains url to scheme+host+port rather than a full path, which is real added meaning. But the capabilities array — the semantically richest parameter, with seven enum values — is never discussed (minimality, read vs interact vs debug granularity), leaving the schema to carry 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: ask the user for access to an exact origin in the Firefox panel. An agent can tell this is a permission-request tool rather than a page action. It stops short of naming which sibling tools this unlocks, so differentiation from the other thirty firefox_* tools is only implicit.

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 clause 'Page content does not authorize actions' implies this tool is needed when access has not already been granted and that page-derived instructions cannot substitute for a user grant. However, it never says to call this before firefox_click/firefox_read_page/firefox_navigate, nor what to do after a denial or whether an existing grant must be re-requested.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful context about required read/capture access and discarding the image after navigation, but it does not describe the return format or other operational limits.

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 short sentences and front-loads the core action. It is efficient, though the access sentence is dense and could be clearer.

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 low-complexity one-parameter tool with strong annotations, the description covers access and navigation invalidation. However, with no output schema, it omits what the screenshot returns and does not clarify the tabId parameter.

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

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

There is one required parameter, tabId, with 0% schema description coverage. The description mentions an "authorized tab" but does not explain what tabId represents, how to obtain it, or any format constraints, 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 description states a specific verb and resource: "Capture an authorized tab." The screenshot intent is clear from the tool name, but the description does not explicitly differentiate this from siblings such as firefox_read_page or firefox_inspect.

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

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

It gives an access prerequisite and a navigation invalidation rule, but no guidance on when to use this tool versus alternatives or when not to use it. The agent must infer the usage context 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?

Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, which is a surprising profile for a scroll and demands explanation the description does not give. It never says what state changes or can be lost, whether scrolling triggers lazy loading, or how it interacts with a scrolled frame. The only added behavior context is the CSS-pixel unit and the 'authorized' 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?

One short sentence, front-loaded with the action and scope, with no filler or redundancy. It is efficient but leans toward under-specification rather than conciseness, so it does not earn 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?

For a four-parameter mutation-flagged tool with no output schema and zero schema descriptions, the definition is far too thin. An agent cannot determine direction conventions, frame targeting, or what the destructive hint implies, all of which it needs before invoking the tool safely.

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 all four parameters (x, y, tabId, frameId) are documented nowhere but their types and numeric bounds. The description only clarifies the unit for x/y; it does not explain sign direction (negative = up/left), what omitting x does, whether frameId defaults to the top document, or how tabId relates to firefox_list_tabs.

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) and target (document or frame) plus the coordinate unit (CSS pixels), which is enough to distinguish it from every sibling such as firefox_navigate or firefox_click. It stops short of naming which sibling to use for page-level vs element-level movement, but the action itself 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as firefox_navigate or firefox_point for reaching offscreen content. The word 'authorized' hints at an access prerequisite but never states what authorization is needed or how to obtain it (cf. firefox_request_access).

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, so the agent knows this mutates live page state; the description adds nothing beyond that. It does not say that selections replace existing values, that the element must be an observed native select, or that a stale snapshot/ref will fail — all material for a destructive tool. No contradiction with the annotations, but the description carries little of its burden.

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 sentence with no filler, which is good, but it is terse to the point of under-specification rather than genuinely concise. There is no structure to front-load beyond the single clause.

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

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

For a five-parameter destructive mutation with no output schema and 40% schema coverage, the description is far too thin. An agent cannot determine required preconditions (prior read_page, valid snapshotId/ref), failure modes, or what state changes result from a successful call.

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 only 40%: ref and snapshotId are documented in the schema, while tabId, frameId, and values have no description anywhere. The phrase 'observed options' hints that values must come from a prior page read, but it never explains the values array semantics (option values vs. labels, multi-select behavior, ordering) which is the single most error-prone 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 verb 'Select' and the resource 'options in a native select control' identify a concrete operation, so the basic purpose is recoverable. But 'observed options' is undefined jargon, and nothing distinguishes this from the sibling tools firefox_click or firefox_fill, which could plausibly also change a form control.

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 when-to-use guidance at all: no statement that this applies only to native <select> elements, no exclusion pointing to firefox_click for custom dropdowns, and no prerequisite that a page read must happen first. The agent must infer the boundary with firefox_fill and firefox_click entirely on its own.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description contributes one genuinely new behavioral fact — that calling it does not confer access — but says nothing about what 'connection state' or 'capabilities' actually contain, which matters since there is no output schema.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its terseness leaves the return content undefined, which is a completeness issue rather than verbosity.

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 simple (no params, no nesting), but with no output schema the description is the only place an agent could learn what 'connection state' and 'extension capabilities' look like in a response. That return-shape information is absent, leaving a real gap for an agent deciding whether this tool answers its question.

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

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

The tool takes zero parameters, so there is no parameter semantics to add; the baseline of 4 applies. Nothing in the description conflicts with the empty schema.

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

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

The description names a specific verb ('Report') and specific resources ('connection state' and 'extension capabilities'), which is enough to distinguish a status probe from action-oriented siblings like firefox_request_access or firefox_list_tabs. It stops short of naming those siblings, so differentiation relies on the reader inferring it from the phrase 'without granting access'.

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 clause 'without granting access' implies this is a safe pre-flight check to run before attempting authorized operations, but the description never says explicitly when to call it or when to prefer firefox_request_access instead. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns no credit merely for implying closing is a write. It does add one useful piece of context beyond annotations: the unsaved-work warning on close. It says nothing about what happens after close (focus shift, whether tabId becomes invalid), nor about rate limits or failures.

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

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

Two short sentences with the operation list front-loaded and the hazard sentence last, which is the right order. No padding, though 'authorized' is a slightly murky qualifier.

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

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

This is a mutation tool with no output schema and two undocumented parameters, so the description should do more than restate the enum. It covers the safety caveat for close but leaves the tabId source and the post-action effects (especially for close and activate) unexplained.

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 carry parameter meaning and does not. The action list merely restates the enum, and tabId gets no explanation at all — no hint that it comes from firefox_list_tabs or what a valid tabId means.

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

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

The description names a specific resource (an authorized tab) and enumerates the concrete operations: activate, reload, pin, unpin, close. That distinguishes it from siblings like firefox_open_tab and firefox_release_tab, though the word 'authorized' is never explained and the boundary with firefox_release_tab is left implicit.

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

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

Use is implied by the action list: pick this when you already have a tabId and need a lifecycle operation. There is no explicit when-to-use vs. an alternative, and no guidance on how it relates to firefox_open_tab (new tab) or firefox_release_tab, which an agent could reasonably confuse with pin/unpin.

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 destructive=true, openWorld=true and idempotent=false, so the description doesn't need to restate the safety profile. It does add non-obvious context: per-tab access requirements and the optional tabGroups permission gate. It omits what 'ungroup' actually does to group state and which parameters each action expects, leaving real behavioral gaps.

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

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

Three short sentences, front-loaded with the capability statement before the constraints. Nothing is redundant; the weakness is under-specification rather than verbosity.

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 destructive, open-world, multi-action mutation tool with six undocumented parameters and no output schema needs more than a capability list. The access and permission notes are valuable, but the per-action parameter applicability and the consequences of 'ungroup' 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 description coverage is 0% for six parameters, so the description carries the full burden and mostly doesn't: it never explains that tabIds is create-only, groupId is for update/ungroup, or that title/color/collapsed only apply to update. The action list merely echoes four enum values already in the schema.

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

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

States a specific verb set (List, create, update, ungroup) applied to a specific resource (native tab groups), and the action list maps onto the action enum. It does not explicitly distinguish itself from nearby siblings like firefox_tab_action or firefox_list_tabs, which is the only reason it falls short of 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?

The only usage-relevant content is a prerequisite: every member tab requires access and the optional tabGroups permission must be granted. There is no guidance on when to choose this over firefox_tab_action or firefox_list_tabs, and no when-not-to-use case despite this tool having destructive capability.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the mutation and risk profile is known. The description adds real context beyond that: 'Navigation protection blocks unauthorized destinations,' which tells the agent the action can be refused for policy reasons. However, it never says what a block looks like (error vs no-op), nor that going back may discard forward history.

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

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

Two short sentences with the action front-loaded and the constraint second; no filler or repetition. It is arguably too terse for a mutating navigation tool, but nothing written is wasted.

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

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

For a destructive, non-idempotent navigation tool with no output schema and zero parameter documentation, the description should explain the blocked-destination failure mode and the effect on existing tab state. It flags the protection mechanism but leaves the agent guessing about outcomes and prerequisites such as holding the tab.

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 is the only place parameter meaning could be added, and it largely isn't. 'Authorized tab' loosely implies tabId must reference a tab the agent has acquired, but nothing is said about direction beyond what the enum already conveys.

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 pair and resource: go back or forward within a tab. This distinguishes it from firefox_navigate (go to a URL) and firefox_history (browsing history listing) without needing to open a schema, though the description never names those siblings explicitly.

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

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

There is no explicit when-to-use guidance and no exclusions or alternatives. An agent must infer that this is for session history traversal rather than URL navigation, and nothing says when to prefer it over firefox_navigate or firefox_history. The only usage constraint given is the vague 'authorized tab' phrase.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotent, so the mutation risk is known. The description adds genuinely new context: the file choice is performed by the user in the extension panel and agent-supplied local paths are ignored, which is important behavioral information. It omits whether the call waits for the user, whether it can time out, and what happens if the user cancels.

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

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

Two short sentences, front-loaded with the action, followed by the key constraint. Nothing is padded, though the phrasing 'Ask the user to choose files in the extension panel' is slightly roundabout compared to 'prompt the user to pick files'.

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

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

With no output schema, the description carries responsibility for return behavior and it says nothing about whether an upload status/identifier comes back or how to poll firefox_upload_status. For a destructive, open-world, user-gated operation the definition is minimal but not misleading.

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 50%: ref and snapshotId are documented in the schema, while tabId and frameId are bare integers with no description anywhere. The description does not compensate — 'observed file input' only loosely implies ref/snapshotId and gives no meaning to tabId, frameId, or their interaction (e.g., which frame's input is targeted).

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: 'Ask the user to choose files ... for an observed file input', which clearly identifies a human-in-the-loop file attachment action tied to a page element. It does not, however, name its closest sibling (firefox_upload_status), so the agent must infer the relationship.

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?

'For an observed file input' implies the precondition that a file input element was already found via a page read, and 'Does not read agent-supplied local paths' is a useful exclusion. But there is no guidance on what to do next (check firefox_upload_status), no mention of when not to use it, and no statement of whether this blocks or returns immediately.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact, that file contents are not returned, but says nothing about what status values exist, whether polling is expected, or how long requests persist.

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 no wasted words. The key constraint is stated immediately and nothing is padded.

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

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

With no output schema, the description carries the burden of explaining what a status response looks like, and it does not enumerate possible states or indicate whether the request ID expires. For a simple one-parameter read tool this is a moderate gap rather than a fatal one.

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

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

Schema coverage is 100% and the single requestId parameter is documented in the schema, so the description need not repeat it. It adds no meaning beyond the schema, which is the expected baseline here.

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: read the status of an upload request. The qualifier 'without returning file contents' sharpens the scope. It does not explicitly name the sibling firefox_upload as the counterpart, but the resource name makes the distinction reasonably 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?

Usage is only implied: an agent can infer this is for polling the state of a request created by firefox_upload. There is no explicit when-to-use, when-not-to-use, or reference to the sibling tool that starts the upload.

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

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

Annotations already cover readOnly/idempotent/no-destruct, so the description earns credit for the extra context it does supply: the hard wait ceiling, that a fresh snapshot is returned, that it requires read access, that it never re-fires clicks, and that navigation aborts the wait. It stops short of saying what happens on timeout (error vs. empty snapshot), which is the one behavior an agent most needs to handle.

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 its scope, then constraints. No filler and nothing repeated from the annotations or schema.

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 six-parameter, no-output-schema tool the description is close to sufficient: it covers the wait target, the ceiling, the cancellation condition, and the fact that a snapshot comes back. The remaining gaps (tabId/frameId meaning, timeout-result behavior) are minor and partly handled by the schema.

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

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

Schema coverage is low at 33%, so the description must compensate, and it partly does: 'visible text or a semantic role' clarifies the text and role fields, 'appear or disappear' explains the state enum, and 'up to 10 seconds' explains timeoutMs's maximum. tabId and frameId are left entirely to the schema, so the compensation is incomplete rather than absent.

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

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

The description names a specific verb (wait), the two target conditions (visible text or semantic role), both directions (appear or disappear), and the return value (a fresh snapshot). That is concrete enough to act on, but it never names or contrasts the nearest sibling, firefox_find, which an agent could easily mistake for this tool.

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

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

The cap ('up to 10 seconds') and the access requirement imply the intended use case of waiting for dynamic content, and 'navigation cancels the wait' hints at a failure condition. There is still no explicit statement of when to choose this over firefox_find or firefox_read_page, and no when-not guidance.

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