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

With no annotations, the description carries the full burden and does well: it discloses the 30-second staleness window and the specific failure mode ('element_no_longer_valid'). It omits whether the click waits for navigation or how the button parameter affects behavior, so it is strong but not complete for a mutation-style interaction.

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 the preferred path front-loaded before the fallbacks, and the staleness/error caveat last. No filler text at all.

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 4-parameter tool with no annotations and no output schema, this covers the critical decision points and one return/error value. The only real gap is the undocumented 'button' parameter and the absence of any note on what a successful click 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 coverage is 0%, so the description must compensate, and it does for three of four parameters: element_index (source and 30s validity), selector (fallback role), and xy (discouraged). The 'button' parameter is never mentioned, leaving its accepted values (left/right/middle) undocumented anywhere.

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

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

States a specific verb ('Click') and resource ('a page element') and signals its browser scope, which separates it from mac_click and phone_tap. It does not explicitly distinguish itself from browser_fill/browser_type, which also target page elements, so sibling differentiation is only partially achieved.

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 preference ordering: element_index first, selector as fallback, xy not recommended. It also names the prerequisite source (latest browser_snapshot) and the validity window, leaving nothing about when/how to choose an input to inference.

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

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

With no annotations provided, the description carries the full burden of disclosure, and it only restates the action. It does not say what is destroyed (open tabs, session/cookies, in-flight downloads), whether the call is idempotent or errors when no browser is running, or what the response contains. For a terminal/cleanup action, these are meaningful 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?

A single short sentence with the action front-loaded and zero filler. It is arguably too terse for a state-destroying operation, 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?

The schema and annotation structures contribute nothing here (no params, no annotations, no output schema), so the description is the only information source and it explains only the action. It omits lifecycle preconditions, effect on session state, and failure modes, which an agent needs to sequence this against browser_launch and the other browser_* calls.

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 nothing for the description to disambiguate and the baseline of 4 applies. No parameter text is needed.

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

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

States a specific verb and resource ("Close the browser") in a form that is unambiguous. Because browsers in this toolset are launched with browser_launch, an agent can infer the pairing without opening the schema. It stops short of the sibling differentiation in the highest band, which would explicitly name the launch/close lifecycle.

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

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

No guidance on when to call this versus leaving the browser open, no mention of prerequisites (must a browser be launched first?), and no warning that closing may invalidate page state needed by other browser_* tools. The agent must infer all of this.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose that arbitrary JavaScript can mutate page state, whether promises are awaited, whether the return value must be JSON-serializable, or what happens on syntax errors/exceptions — all critical for a code-execution 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 tight sentence with no filler and the core action front-loaded. It's efficient, though the terseness leaves no room for the missing behavioral detail.

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 high-power arbitrary code execution tool with no annotations, no output schema, and an undocumented parameter, the description is far too thin. An agent cannot confidently predict side effects or the shape of the returned result.

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

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

One parameter with 0% schema description coverage. The name 'js' hints at content, but the description says nothing about expected form (expression vs. function body), whether it is wrapped in an async context, or how the value is captured — details the schema leaves entirely blank.

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

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

States a specific verb (evaluate) and resource (JavaScript in the page) plus the return behavior. It is clear enough to distinguish from browser_read or browser_snapshot, though it 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?

No guidance on when to use this instead of browser_read, browser_snapshot, or browser_click. An agent gets no signal about what this tool is appropriate for (extracting computed values? triggering page state?) versus other browser tools.

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

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

No annotations are provided, so the description carries the whole burden. It does disclose one genuinely useful behavioral trait — that the existing value is fully replaced rather than appended — but says nothing about failure behavior, auto-waiting/retries, whether input/change events are dispatched, or what a successful call 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?

A single sentence with zero waste: the action and its scoping semantics come first, the sibling differentiation second. Nothing to trim and nothing buried.

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

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

The tool is simple and has no output schema or annotations to reconcile, but with 0% schema coverage and no required-parameter marking in the schema, the description should still state the selector format and at least hint at failure behavior. It is adequate for the happy path only.

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 two parameters are undocumented structurally; the description only partially compensates by implying selector identifies the target element and value is the replacement text. No detail on selector syntax (CSS vs XPath), whether value is optional, or why 0 params are marked required.

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

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

States a specific verb+resource ("Fill an input field matched by selector") and immediately contrasts with the sibling browser_type by semantics (replace vs append). An agent can distinguish browser_fill from browser_type without consulting either schema.

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

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

Explicitly names the alternative browser_type and the condition that selects it: fill replaces the whole value, while browser_type appends keystrokes. Missing is any guidance on prerequisites or edge cases (element not found, non-editable elements, whether it waits for the element), so it stops just short of full when/when-not coverage.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the profile is persistent and that the browser is headed by default, but it omits behavior such as what happens if a browser is already running, whether it blocks until ready, or what session handle is returned.

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 parenthetical efficiently covers the key default and override.

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

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

For a simple launch tool with one parameter and no annotations, the description covers purpose and the headless option. However, it lacks context about launch lifecycle, session identity, and interaction with existing browser sessions, which an agent needs to invoke it reliably.

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

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

Schema coverage is 0%, but the description compensates by explaining the sole parameter: headless defaults to false and should be passed as true for headless mode. The only gap is that additionalProperties is true, and the description does not mention other accepted options.

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: 'Launch the browser with a persistent profile.' This clearly distinguishes it from browser_navigate, browser_close, and other browser interaction tools, though it does not explicitly name alternatives.

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

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

The description explains the headless parameter default but gives no guidance on when to call browser_launch versus browser_navigate or other sibling tools. It implies a launch step is needed but does not state prerequisites or sequencing.

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

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

With no annotations, the description carries the full burden and does add non-obvious value by disclosing that file:// is rejected unless NORACU_ALLOW_FILE_URL=1. It omits important mutation behavior: whether navigation waits for page load, what happens if no tab exists, and whether it errors or auto-opens a browser.

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 by the one surprising constraint. Nothing wasted.

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

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

For a one-parameter navigation tool with no output schema, the core is covered: action, target, and the notable scheme restriction. Only the preconditions (existing tab/session) and load-completion semantics 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?

The single parameter has 0% schema description coverage, so the description must compensate. It does constrain the value to an http(s) URL, which adds meaning beyond the bare 'string' type, but gives no format, normalization, or relative-URL guidance.

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 ('Navigate the current tab to an http(s) URL'), and the phrase 'current tab' implicitly distinguishes it from browser_launch, which creates a session. It stops short of explicitly naming the sibling, but an agent can tell the two apart.

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: 'current tab' suggests an existing browser session must be open, but the description never says so nor directs the agent to browser_launch if none exists. The file:// restriction is a constraint rather than when-to-use guidance.

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

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

With no annotations, the description carries the full burden but says nothing about where the event is dispatched (focused element vs page), whether modifier chords work cross-platform, or what is returned. For a synthetic-input tool whose effect depends entirely on focus state, that is a meaningful 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 short sentence with the essential format hint front-loaded and no filler. It is terse rather than padded, which is appropriate for a one-parameter tool.

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

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

For a simple one-param tool with no output schema, the description covers purpose and input format adequately. It still leaves out the focus/target context that determines whether the press has any effect, which is the one thing an agent could get wrong.

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

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

Schema description coverage is 0%, so the description must compensate; the examples 'Enter' and 'Control+A' do convey the accepted key/chord string format, which is the key semantic. However it never explains that the parameter is optional per the schema, nor any default behavior when 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?

States a specific verb and resource ('Press a key or chord') plus concrete examples, so the agent knows this synthesizes keyboard events in the browser. It does not explicitly contrast with browser_type or mac_key, so sibling differentiation 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?

No guidance on when to use this versus browser_type (text entry) or browser_fill, and no preconditions such as requiring a focused element or a prior browser_snapshot. The examples imply the format but not the selection context.

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

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

With no annotations, the description carries the full disclosure burden. It usefully reveals that only *visible* text is returned (excluding hidden nodes, scripts, and styles), but says nothing about behavior on selector mismatch, truncation, whitespace normalization, or whether the call is a no-side-effect read.

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?

Single sentence with zero filler and the core action front-loaded. It is efficient, though the terseness contributes to the gaps in the other dimensions.

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, no annotations, and no schema descriptions, so the description must explain return shape — and it does not (string vs. list of text nodes, whether element boundaries are preserved). For a content-extraction tool with overlapping siblings, this leaves the agent guessing.

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% — the single parameter is an undescribed string. The description only establishes that the selector is optional and scopes the read; it never says whether it is a CSS selector, XPath, or text matcher, nor what the default scope is when 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 states a specific verb and resource ("Read the page's visible text") plus the optional scoping mechanism, so an agent knows exactly what operation this performs. It stops short of distinguishing itself from close siblings such as browser_snapshot and browser_evaluate, which also surface page content.

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

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

There is no statement of when to use this instead of browser_snapshot (structured page state) or browser_evaluate (arbitrary JS) when extracting content. The phrase "optionally scoped to a selector" hints at a narrowing use case but gives no explicit conditions or prerequisites such as requiring a page to be loaded first.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: it returns the image plus DPR/viewport metadata, quality only applies to jpeg, and the option set is enumerable. It omits the default capture mode (viewport vs full page) and any prerequisite that a page must already be loaded.

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 sentence, front-loaded with the verb and resource, then densely packing options and return value. No filler; every clause adds 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 4-param tool with a nested object, no output schema and no annotations, the description covers both the option surface and the return payload. It lacks only prerequisites (browser launched/navigated) and default behavior to be fully self-sufficient.

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

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

Schema coverage is 0%, yet the description compensates well: it explains fullPage, format values png|jpeg, quality range 1-100 restricted to jpeg, and the clip object's {x,y,width,height} shape. The only gap is that defaults (e.g. fullPage=false, default format) are unstated.

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 (Screenshot) and resource (the page), which implicitly distinguishes it from the mac_screenshot and phone_screenshot siblings. It doesn't explicitly name or route against those alternatives, 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?

There is no when-to-use guidance, no conditions, and no mention of the mac_screenshot/phone_screenshot alternatives an agent must choose between. Usage is only inferable from the word '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?

No annotations are provided, so the description carries the full burden. It says the tool scrolls a page, but does not disclose what constitutes a page, whether scrolling is immediate or smooth, behavior at page boundaries, defaults for omitted parameters, or any return information.

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 compact sentence with no wasted wording. The action and scope are front-loaded immediately.

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

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

For a simple UI-action tool with no annotations, no output schema, and no parameter descriptions in the schema, the one-sentence description leaves important gaps. An agent cannot confidently infer defaults, valid direction strings, or page-size behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that pages refers to number of pages and direction refers to up or down, but does not specify valid direction values, whether pages accepts negative or fractional values, or what happens when either optional parameter is omitted.

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

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

States a specific verb and resource: scroll the page up or down by a number of pages. The browser context is clear from the tool name and page wording, though it does not explicitly differentiate itself from platform-specific siblings such as mac_scroll or phone_swipe.

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

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

Provides no guidance on when to use this tool versus alternatives such as browser_read, browser_snapshot, or mac_scroll. It also does not mention prerequisites, expected page context, or when scrolling is preferable to navigation.

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

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

No annotations exist, so the description carries the full burden. It does disclose the two return components (ARIA tree and index list) and the downstream linkage to browser_click, which is valuable. But it omits whether browser_id defaults to a specific browser, whether the snapshot reflects the current page state, and gives no warning that ARIA snapshots can be very large.

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 sentence, front-loaded with the primary return value, with the actionable linkage to browser_click packed into a short parenthetical. Nothing is wasted or buried.

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

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

With no output schema and no annotations, the description has to do more work than it does. It covers what comes back and how to use the result, but leaves the optional/required nature of browser_id and the expected size of the ARIA payload 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?

There is one parameter (browser_id) with 0% schema description coverage, and the description never mentions it or explains its role. With a single undocumented parameter and no description compensation, the agent must guess how to target a browser. The stated 'feed browser_click' hint applies to output indexes, not to this input.

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: return the page's ARIA accessibility snapshot plus a clickable element index list. That clearly distinguishes it from browser_screenshot (visual capture) and browser_read (text extraction). Sibling differentiation is only indirect, achieved through the parenthetical naming browser_click.

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

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

The parenthetical '(indexes feed browser_click)' implies the intended workflow of snapshotting before clicking, which is genuinely useful guidance. However, it never states when to prefer this over browser_screenshot, browser_read, or browser_evaluate, and gives no exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that typing targets the focused element and appends keystrokes, but it does not state what happens when nothing is focused, whether it triggers normal keyboard events, or what the call 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?

The definition is one tight sentence with no filler. The core action and the append-versus-replace distinction are both front-loaded.

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

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

For a simple one-parameter browser action, the description covers the main purpose and the focused-element precondition. However, with no annotations and no output schema, it still leaves error behavior and return semantics unstated.

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 should compensate. It clarifies that the text parameter is entered as keystrokes and appended rather than replacing existing content, but it does not address the fact that the text field is not marked required or specify any content constraints.

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: type text via the keyboard into the focused element. It also explicitly distinguishes this action from browser_fill, so an agent can tell the two typing tools apart without opening their schemas.

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

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

It names the key alternative and the condition that selects it: browser_type appends keystrokes, while browser_fill replaces the whole value. That is exactly the decision an agent needs to make between these sibling tools.

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

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

With no annotations, the description carries the burden and does well: 30-second index validity, default menu-bar pruning, depth clamping, and the ax_empty failure mode with its likely causes (not frontmost / another Space). It omits macOS Accessibility permission prerequisites and output volume/size considerations.

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 dense, front-loaded paragraph with parenthetical detail rather than wasted sentences. It is slightly over-packed — the return-field list, TTL, pruning rule, and error case all compete in a single run-on — but nothing 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?

Covers return fields, default behavior, parameter bounds, downstream consumers, and the empty-result case, which is strong for a 2-param read tool with no output schema. The unresolved app-parameter semantics and missing permission note keep it from being fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It fully documents depth (default 3, clamped 1-10), but the app parameter is only called "optional app name" without explaining whether it targets a non-foreground app, which contradicts the "foreground app" framing in the opening clause.

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

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

Opens with a specific verb+resource ("Read the foreground app's accessibility tree") and immediately enumerates the returned fields, so an agent knows exactly what it gets. It also distinguishes itself from mac_screenshot and browser_snapshot by being the AX-tree reader and clarifies its role as the index source for mac_click/mac_drag.

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?

States the menu-bar exception explicitly and routes it to mac_menu_command, and the "indexes feed mac_click/mac_drag for 30s" clause implies the read-then-act workflow. It lacks an explicit "call this first when you don't know element indexes" statement, but the context is clear.

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

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

No annotations exist, so the description carries the full burden, and it does disclose a real behavioral trait: the 30-second staleness window on element_index and the specific failure mode element_no_longer_valid. It omits other useful traits such as whether the click steals focus or what a right-click triggers.

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 zero filler, and the core action plus targeting modes are front-loaded before the staleness caveat.

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

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

With no annotations, no output schema, and five undocumented parameters, the description covers the essentials an agent needs to invoke it correctly, including the cross-tool dependency and error code. Minor gaps remain around coordinate frame and default button/count behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it enumerates the button values (left|right|middle), explains count as repetition, and ties element_index to mac_ax_state and its validity window. It does not clarify whether x/y are screen-absolute or window-relative, nor default values for count or button.

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

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

States a specific verb (click) with two precise targeting modes (coordinates or UI element) plus the optional button and count modifiers. An agent can immediately distinguish this from mac_drag, mac_scroll, and mac_key without inspecting any schema.

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

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

Gives an explicit prerequisite for the element path: use element_index from the latest mac_ax_state, valid for 30s. It does not say when to prefer coordinates over element_index, so the choice between the two modes is 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?

No annotations, so the description carries the full burden. It discloses a real behavioral trait — a 30s validity window and an element_no_longer_valid error on stale indices — which is valuable beyond the schema. It does not describe what a successful drag returns or any permission needs.

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 tightly-packed sentences with zero waste; the core action is front-loaded and the precondition follows.

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

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

For a 2-param, no-annotation, no-output-schema action tool, the description covers the action, input source, staleness window, and a specific error token. Only success behavior and return details are absent, which is minor.

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

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

Schema coverage is 0%, so the description must compensate. It does clarify where the integers come from (element indices from mac_ax_state) and their freshness requirement, which is genuinely useful, but adds no format, range, or failure behavior for the parameters themselves.

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 (drag) and resource (UI element to UI element) with concrete use cases (windows, sliders, selections). This implicitly distinguishes from mac_click (a click) and mac_scroll, but never names the alternative 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?

Gives a concrete precondition and operational constraint: use from_index/to_index from the latest mac_ax_state, valid for 30s. No explicit when-not-to-use or named alternative tool guidance, so not a 5.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuine behavioral trait: the frontmost-app guard that causes the press to be refused. It says nothing about what a refusal looks like (error vs. silent no-op), whether keys auto-repeat, what focus state is needed when `app` is omitted, or what the tool 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 sentences, zero filler, and the core action with format examples is front-loaded ahead of the conditional focus-guard clause. Nothing needs trimming or reordering.

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 tool with no output schema and no annotations, the description covers both parameters plus a failure-mode guard, which is close to sufficient. It falls short only on outcome reporting — an agent still cannot predict whether a refused press raises an error or returns a status.

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

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

Schema coverage is 0%, so the description must compensate and does: `key` is explained by example for both plain keys and modifier chords, and `app` gets a precise meaning (frontmost focus guard). What is still missing is whether `key` values are case-sensitive or platform-specific beyond the 'cmd'/'arrow-up' examples.

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

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

Specific verb ("Press") plus resource (a key or modifier chord) with concrete examples ('return', 'cmd-shift-v', 'arrow-up') that make the accepted key syntax immediately legible. It does not name the siblings it differs from (mac_type, mac_paste, browser_press_key), so an agent must infer that this is the single-keystroke/shortcut tool rather than text entry.

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

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

The description states a real usage condition for `app`: input is refused unless that app is frontmost, framing it as a focus guard. But it gives no guidance on when to choose this over mac_type or mac_paste, nor when the focus guard should be used versus omitted — that choice is left implicit.

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

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

With no annotations, the description carries the full burden. It usefully discloses the mechanism (accessibility traversal) and a behavioral trait (locale-safe), but omits key behavior: whether the app must be running/frontmost, accessibility permission requirements, what happens if the command isn't found, and whether this mutates app state with side effects.

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

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

A single efficient sentence with the action front-loaded and no wasted clauses. It is arguably too terse given the undocumented parameters, but as written every word earns its place.

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

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

With two undocumented parameters, no annotations, no required-field declaration, and no output schema, the description needs to compensate and does not. It explains the mechanism but not how to construct a valid call or what the result looks like, leaving an agent to guess the menu path syntax.

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 both parameters. The description only loosely gestures at 'app' and 'command' without specifying formats: is 'app' a bundle ID, process name, or display name? Is 'command' a menu path like 'File > Save', a single item, or a command ID? This is a critical gap for a traversal-based tool.

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 ('Run') and resource ('an app's menu bar command') plus the mechanism ('accessibility traversal'), which distinguishes it from siblings like mac_click or mac_key. It stops short of naming a sibling or contrasting, but the action 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?

Usage is implied: invoke this to trigger a menu bar item rather than clicking a coordinate or sending keystrokes, and 'locale-safe' hints at when to prefer it. However, there is no explicit 'use this when... / use X instead when...' guidance, and no stated prerequisites such as accessibility permissions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool overwrites the clipboard, pastes via Cmd+V, and can refuse input unless a specified app is frontmost, but it omits permissions requirements, error behavior, and what happens when no app is supplied.

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

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

The description is two tight sentences with no wasted words, and the core action is front-loaded before the focus-guard caveat.

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

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

For a simple two-parameter tool, the description covers the main action and one important safety behavior. However, gaps around app identifier format, optional parameter defaults, and error/return behavior keep it from being fully 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 must compensate. It explains that app acts as a focus guard and implies text is the content to paste, but it does not specify the expected app identifier format, defaults, or requiredness.

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 action and mechanism: it writes text to the clipboard and pastes it via Cmd+V. This distinguishes it functionally from typing tools like mac_type, though it does not explicitly name or compare those alternatives.

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

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

There is no explicit guidance on when to use this tool instead of alternatives such as mac_type or mac_key. The only conditional guidance is about the app focus guard, which describes behavior rather than tool selection.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the return shape ({scale, logical_size, screen:'main'}), scopes output to the main display, and explains the pixel-to-point conversion needed for subsequent clicks. It omits that this is a read-only operation and any macOS screen-recording permission requirement, which is the main remaining gap.

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

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

Two dense sentences, front-loaded with the core action, then crop behavior, then output shape and coordinate units. No filler, and 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?

No output schema exists, so the description must explain returns — and it does, at least for scale, logical_size and screen. It doesn't say which field carries the base64 image payload or whether multiple displays are supported beyond 'main display', leaving minor ambiguity for a nested-object 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?

The single 'region' parameter is a nested object with 0% schema description coverage and no properties defined in the schema, so the description's '{x,y,w,h}' breakdown is essential and well-targeted. However it doesn't clarify optionality semantics (partial region? defaults? validation), so it compensates only partially 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 ('Capture the Mac screen as PNG base64') plus an optional crop, and the platform qualifier 'Mac' separates it from sibling screenshots like browser_screenshot and phone_screenshot. It stops short of explicitly naming those siblings, but the domain is unmistakable.

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 implied rather than stated: the note that 'click coordinates are in points (pixels / scale)' hints that this tool pairs with mac_click/mac_drag, but no explicit when-to-use or when-to-prefer-an-alternative guidance is given. An agent must infer the screenshot-then-click workflow.

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

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

With no annotations, the description carries the full behavioral burden and does add an important side effect: it moves the pointer over the target window first. It does not disclose permission requirements, behavior when no window is frontmost, whether scrolling is smooth or instant, or what the tool 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?

The definition is a single front-loaded sentence with zero waste. It packs the action, target, parameters, default, and pointer side effect into one readable line.

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

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

For a simple two-parameter tool with no output schema and no annotations, the description covers the action, target, both parameters, the default, and a notable side effect. It is nearly complete, with only permission and failure-mode details 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%, so the description must compensate, and it does: it defines the direction domain as up/down/left/right and states the pages parameter defaults to 1. It does not clarify whether fractional or negative page values are valid, but both parameters receive meaningful semantic context.

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

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

The description uses a specific verb and resource ('Scroll the frontmost window') and scopes it to Mac frontmost-window scrolling. It implicitly distinguishes from browser_scroll and phone_scroll by naming the frontmost window, but does not name a sibling explicitly as the high-scoring example does.

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 implied by the context of scrolling the frontmost window, and the default page count is stated. However, there is no explicit guidance on when to use this versus mac_key, mac_drag, or other navigation tools, nor any prerequisites or exclusions.

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

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

With no annotations, the description carries the full burden and delivers real behavioral detail: typing occurs at the current focus, no modifier keys are sent, input is refused unless the named app is frontmost, and keystrokes can be re-segmented under a CJK IME. What's missing is failure behavior when nothing is focused and whether typing is per-character or a single injection.

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, each carrying distinct information (core action, focus-guard parameter, IME warning plus alternative), front-loaded with the primary behavior. No filler.

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

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

For a two-parameter input tool with no annotations and no output schema, this covers purpose, a safety-relevant parameter, a real hazard with a workaround, and the preferred alternative. Return/error reporting is the only notable omission.

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

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

Schema coverage is 0%, so the description must explain both parameters. It defines 'app' precisely (focus guard: refuse input unless that app is frontmost) and makes 'text' clear from the verb. Minor gap: it doesn't state whether app is optional or what happens if 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?

States a specific verb and target: 'Type text at the current focus without modifier keys.' The 'without modifier keys' clause implicitly separates it from mac_key, and it names mac_paste as the alternative, so an agent can pick between them without reading schemas. It stops short of explicitly naming mac_key as the sibling it differs from.

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

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

Gives a concrete use-this-instead rule for the IME case ('use mac_paste for reliable text entry') and explains the app parameter's focus-guard semantics. No guidance for when NOT to use it outside the IME scenario, and no prerequisites such as needing a focused target window.

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

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

With no annotations, the description carries the full burden and does well: it flags the tool as EXPERIMENTAL, explains the primary mechanism, notes a dependency condition, and discloses a fallback path. It stops short of describing expected outcomes or failure behavior if both paths fail.

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

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

The description is a single efficient sentence with the experimental warning front-loaded and the mechanism plus fallback packed in without waste.

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

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

For a simple no-parameter UI action with no output schema, the description is nearly complete: it gives the action, implementation path, fallback, and experimental status. Minor gaps remain around expected outcome and failure handling if both mechanisms fail.

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

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

The tool has zero parameters, so parameter semantics are inherently simple. The baseline for 0 params is 4, and no parameter-related information is missing.

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: "Open the iPhone App Switcher." It also names the mechanism (iPhone Mirroring menu) and fallback (imctl gesture), making the action distinct from siblings like phone_home or phone_tap.

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 implied by the action itself, and the description adds a useful condition: it works without python/pyobjc when the mirror is connected. However, it does not explicitly say when to choose this over alternatives or when not to use it.

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

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

With no annotations, the description carries the full burden. It does disclose the experimental status and external dependencies, which is genuinely useful behavioral context an agent can act on. It omits what happens when the text is not found, whether it only reads or also interacts, and what the 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?

Three short sentences with the EXPERIMENTAL caveat front-loaded, which is the right ordering for a warning. Nothing is wasted, though the brevity is partly under-specification rather than economy.

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

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

With no annotations and no output schema, the description should explain what is returned (coordinates, bounding boxes, match count?) and what failure looks like. For a tool whose whole value is the located result, that gap is material.

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

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

The single 'text' parameter has 0% schema description coverage, so the description must compensate and does not: no indication of exact vs. substring vs. regex matching, case sensitivity, or whether the string targets visible UI labels. Only the verb 'locate' hints at intent.

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: 'Locate text on the iPhone screen.' An agent can distinguish this from the mac_* and browser_* families by platform. It does not differentiate from the sibling phone_ocr, which plausibly overlaps (find text vs. read text), 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?

Gives real prerequisites (iPhone Mirroring, python3 with pyobjc) and flags EXPERIMENTAL, which tells the agent this may fail and needs setup. But it never says when to choose this over phone_ocr or phone_tap, nor what conditions make it unusable.

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

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

With no annotations, the description carries the full burden and does well: it discloses the preferred path (iPhone Mirroring menu), the dependency (no python/pyobjc needed when mirrored), the fallback (imctl swipe), and the experimental stability caveat. It omits what happens if both paths fail and whether there is any latency or confirmation, keeping it short of 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?

A single front-loaded sentence with the EXPERIMENTAL risk flag first, then the action, then the fallback. Dense but every clause (menu path, dependency, fallback) carries real information; the parenthetical is slightly heavy 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?

For a zero-parameter, annotation-free, output-schema-free action tool, the description covers purpose, precondition, implementation path, and fallback. The remaining gap is failure behavior — what the agent sees if neither the mirror nor imctl succeeds — which matters for an EXPERIMENTAL 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?

The tool takes zero parameters, so the baseline is 4. The absence of an input schema is fully consistent with the description, which describes an action requiring no arguments.

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

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

States a specific verb and destination: 'Go to the iPhone Home Screen', which is unambiguous. It does not explicitly contrast with phone_app_switcher or phone_launch, but the target (home screen) is distinct enough that an agent can pick it without opening the schema.

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

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

Usage context is implied rather than stated: the tool is marked EXPERIMENTAL and works 'when the mirror is connected', which hints at a precondition. It never says when to prefer this over phone_swipe, phone_app_switcher, or phone_launch, so routing between siblings is 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?

With no annotations, the description carries the full burden. It discloses the experimental status and the environment requirements, which is real value beyond structured fields, but it doesn't say what state is required (active session, focused app) or what an error or success 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?

Three short clauses, with the EXPERIMENTAL warning and environment requirement front-loaded before the action. Nothing is redundant, though the sentence fragments could be tightened into a single statement.

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

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

For a one-parameter tool with no annotations or output schema, the description covers prerequisites and valid inputs but leaves out the runtime state needed for it to succeed and any indication of failure modes. Adequate to attempt the call, not to call it reliably.

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

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

Schema coverage is 0% and the schema types 'key' only as a plain string, so the description's enumeration of the six valid key values is the only source of that constraint. It stops short of saying whether 'key' is required or what the default is when omitted (required is 0).

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 ('Press a key') and the exact key set (return, delete, up, down, left, right), and the iPhone Mirroring prerequisite makes clear it targets the mirrored iPhone rather than the Mac. It doesn't explicitly name mac_key or browser_press_key as alternatives, but the phone scope is discernible.

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 prerequisites (iPhone Mirroring running, python3 with pyobjc) tell the agent when the tool can work at all, which is genuinely useful context. It never says when to choose this over mac_key or browser_press_key, nor what happens if mirroring is not active, so usage is only implied by the sibling naming.

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

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

With no annotations, the description carries the full behavioral burden and adds useful context: EXPERIMENTAL status, python3/pyobjc dependency, need for iPhone Mirroring to be frontmost, and handling of a paused connection. However, it omits success/failure behavior, side effects, and what 'clicks Resume' entails.

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 EXPERIMENTAL, and each sentence carries prerequisite information. Slightly awkward phrasing ('and clicks Resume') blurs the actor but does not waste space.

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

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

For a zero-param launch tool the description is missing the central outcome—what gets launched and what the agent should expect after invocation. It compensates with environment prerequisites but not enough for full completeness given no annotations or output 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?

There are zero parameters, so the baseline is 4; the description need not explain inputs. Schema coverage is effectively 100% for an 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 enumerates dependencies and a Resume interaction but never states the core action in verb+resource terms; an agent must infer from the name that it launches iPhone Mirroring. It does not distinguish phone_launch from siblings such as phone_open or phone_status.

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

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

It gives prerequisites (iPhone Mirroring running/frontmost) but no when-to-use condition relative to phone_open, phone_status, or other phone tools. No alternatives or exclusions are named.

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

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

No annotations are provided, so the description carries the full burden. It discloses experimental status and runtime prerequisites, which is useful, but does not explain side effects, failure behavior, waiting semantics, return values, or permission constraints.

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 with no wasted text. The experimental warning is front-loaded, followed by prerequisites and the core action, making it easy to scan.

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

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

For a three-parameter gesture tool with no annotations and no output schema, the description covers the action and dependencies but leaves important gaps: coordinate system, default duration, return/error behavior, and interaction side effects.

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

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

Schema description coverage is 0%, so the description must compensate. It identifies x and y as coordinates and duration as optional seconds, but leaves coordinate origin/units, valid ranges, and the default duration unspecified, and it does not address why no parameters are marked required.

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 target: 'Long-press at {x, y}' with an optional duration. This clearly identifies a phone gesture action. It does not explicitly contrast with siblings like phone_tap or phone_swipe, so it falls short of full sibling differentiation.

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

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

The tool's usage is implied by the gesture name and the prerequisite context ('Needs iPhone Mirroring and a python3 with pyobjc'). However, there is no explicit guidance on when to choose long-press versus phone_tap, phone_swipe, or other 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?

Beyond the lack of annotations, it provides crucial behavioral context by labeling the tool as 'EXPERIMENTAL' and detailing the execution environment requirements. This manages user expectations regarding stability and setup.

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 definition is concise and effective, front-loading the experimental status and environment requirements before stating the core function.

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

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

Given that the tool has no configurable parameters, detailing the environment and operational constraints (Mirroring, Python version) makes the description maximally complete.

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

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

The schema has zero parameters, meaning the baseline for this dimension is high. The description adds no semantic meaning to non-existent parameters but is entirely appropriate for a zero-parameter tool.

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

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

The description clearly defines the tool's function as OCR of the iPhone screen into text with coordinates. This differentiates it from other screen-based interaction siblings like phone_screenshot or phone_type.

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

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

It explicitly outlines critical environmental prerequisites necessary for the tool to function, namely needing iPhone Mirroring and a specific Python setup (python3 with pyobjc).

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

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

With no annotations at all, the description carries the full burden and does well: it flags EXPERIMENTAL, names the runtime dependencies, spells out the Spotlight/type/OCR/tap sequence, and discloses the fallback behavior on non-match. Remaining gaps are latency, whether the device must be unlocked, and what a failure looks like to the caller.

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 dense sentence that front-loads the EXPERIMENTAL warning and prerequisites before the operational detail. No filler.

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

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

No output schema and no annotations mean the description must cover both semantics and results. It explains the invocation path and the not-found fallback, but says nothing about what is returned on success, how long the OCR matching takes, or error conditions beyond not-found.

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

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

One parameter at 0% schema coverage, and the schema allows arbitrary extra properties. The phrase 'type the name' implies the app param is the app name to search for, which is real added meaning, but it never states matching rules (exact vs partial, case sensitivity, localized names) that OCR row-picking would depend on.

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 and resource: 'Open an app' on a mirrored iPhone, plus the actual mechanism (Spotlight command, type name, OCR-pick row, tap). However it never distinguishes itself from the very close sibling phone_launch, which by name appears to do the same job, so an agent cannot pick between them from this text.

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

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

The description gives prerequisites (iPhone Mirroring, python3 with pyobjc) but no guidance on when to prefer this over phone_launch or the mac_* alternatives. 'Returns to the home screen when not found' hints at a failure path but no selection criteria are 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?

With no annotations, the description carries the full burden. It earns credit for disclosing dependencies and the non-obvious capture-by-window-id behavior that works even when the window is occluded. It does not say what is returned (image payload vs. file path) or what happens on failure, which an agent needs for a no-annotation 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?

Two compact sentences with zero filler, and the most decision-relevant token (EXPERIMENTAL) is front-loaded ahead of the prerequisites and the behavior.

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

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

For a zero-parameter tool, prerequisites and the occlusion-proof capture quirk are the key unknowns, and both are covered. The remaining gap is the return format, which no output schema compensates for.

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

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

Zero parameters, so the baseline is 4 per calibration; there is nothing for the description to disambiguate and the empty schema is self-evident.

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: 'Screenshot the iPhone screen', with the target qualified as the Mirroring window. Among siblings mac_screenshot and browser_screenshot, the device qualifier makes the distinction immediate without opening any schema.

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

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

It states hard prerequisites (iPhone Mirroring running, python3 with pyobjc) and flags EXPERIMENTAL status, which implies 'use only if you have this setup'. But it never says when to pick it over phone_ocr or mac_screenshot, nor what to do when the prerequisites are unmet.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses experimental status, external runtime dependencies, the underlying mechanism (trackpad-style scroll events), and a concrete default of 0.5 window heights. It omits failure behavior and return values, but for a non-destructive scroll action the disclosed surface is substantially above bare minimum.

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, no filler, and the most decision-relevant facts (EXPERIMENTAL, prerequisites) are front-loaded before the action description. 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 two-optional-parameter tool with no annotations and no output schema, the description covers environment requirements, semantics of the primary parameter, and the default. The remaining gap is the undocumented direction value set, which is the one thing that could cause a failed 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 0%, so the description must compensate. It explains `distance` well (units = window heights, default 0.5) but says nothing about the accepted values of `direction` beyond 'up or down' in prose, and the schema declares it as an unconstrained string with no enum — an agent cannot know whether 'up'/'down', 'Up'/'Down', or something else is expected.

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: scroll the list under the iPhone mirror by a distance in window heights, using trackpad-style events. This is clearly distinct from mac_scroll and browser_scroll through the 'under the mirror' scoping, though it never explicitly contrasts itself with phone_swipe, the closest sibling.

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

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

Gives useful preconditions (iPhone Mirroring must be active, python3 with pyobjc installed, EXPERIMENTAL flag) which implicitly tells the agent when the tool is usable. It does not say when to prefer this over phone_swipe or mac_scroll, nor what to do when the prerequisites are unmet.

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

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

With no annotations, the description carries the full burden and does disclose key operational facts: experimental status, the iPhone Mirroring dependency, and the pyobjc/python3 requirement. It does not state that the call is read-only (inferable from 'status'), what happens when mirroring is not running, or what the individual fields ('live', 'overlay', 'paused') mean.

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: the 'EXPERIMENTAL' warning and prerequisites come first, then the return shape. The parenthetical field list is dense but functional; 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 no output schema, listing the returned JSON fields (running, window, onscreen, frontmost, live, overlay, paused) is the right compensating move, and the prerequisites are stated. The only gap is that the meaning of the less obvious fields is not explained, which matters for interpreting the result.

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 nothing to document and the baseline is 4. The schema is fully described and the description correctly adds no spurious parameter narrative.

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 ('Return') and resource ('iPhone Mirroring session status') plus the return format (JSON). It is clearly distinguishable from siblings like phone_launch or phone_screenshot, which act on the phone rather than report state, though it never explicitly contrasts itself with them.

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

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

Usage is implied by the 'status' framing — check state before or after driving the phone — but there is no explicit 'use this when...' or 'use X instead' guidance. The 'EXPERIMENTAL' and prerequisite notes give context for when it will fail, not when to prefer it.

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

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

With no annotations, the description carries the full burden and does real work: it flags the tool as EXPERIMENTAL and discloses host dependencies (iPhone Mirroring, pyobjc) plus the fact that it emulates a mouse drag rather than a native touch. It does not say what happens on failure, whether the call blocks for the duration, or what the return value is, which keeps it below 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?

A single tight sentence, front-loaded with the EXPERIMENTAL warning and prerequisites before the operational detail. No redundant restatement of the name or title.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers prerequisites, purpose, parameters, and sibling routing. The remaining gaps — coordinate semantics, default duration, and error/return behavior — are real but secondary for a fire-and-forget gesture tool.

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

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

Schema description coverage is 0%, so the description must compensate; it does name all three parameters — 'from [x,y] to [x,y]' and 'optional duration in ms' — which is more than the bare schema provides. It omits coordinate-space details (screen vs device points, array length/ordering) and the default value for ms, so it is not fully self-sufficient.

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

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

States a specific verb+resource: swipe (mouse drag) from an [x,y] point to another over an optional duration, with the target use case (Home Screen paging) named. It also explicitly distinguishes itself from phone_scroll for list movement, so an agent can separate it from the nearest sibling without opening the schema.

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

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

Gives the use case ('gestures such as Home Screen paging') and an explicit exclusion routing to phone_scroll 'to move a list'. It also states prerequisites up front (iPhone Mirroring, python3 with pyobjc), which is exactly the when-can-I-use-this information an agent needs.

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

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

With no annotations, the description still discloses the experimental status, the runtime prerequisites, and the specific error surface ('refused with mirror_not_live when the mirror is paused'), which is the kind of mutation-safety context an agent needs. It stops short of describing what a successful tap returns or any confirmation side-effects.

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

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

Four short sentences, front-loaded with the experimental warning, and every clause carries information an agent needs (warning, prerequisites, coordinate convention, failure mode).

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

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

For a simple two-axis pointer tool with no output schema, the description covers the critical unknowns: environment dependency, coordinate convention, and the primary failure mode. Only the coordinate origin and post-tap verification are unaddressed.

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

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

Schema coverage is 0% and both parameters are undocumented there, so the description must carry the load; it does add the key fact that coordinates are normalized 0-1, but it omits the origin corner and the fact that both are optional per 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-resource pair ('Tap at {x, y}') and anchors it to iPhone Mirroring, so an agent can tell it apart from mac_click and phone_scroll without opening the schema.

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

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

It gives prerequisites ('Needs iPhone Mirroring and a python3 with pyobjc') and a refusal condition, but never says when to prefer this over phone_find, phone_longpress, or mac_click, nor what to do instead when the mirror is paused.

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

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

With no annotations, the description carries the full burden, and it does disclose useful traits: EXPERIMENTAL status, a hard dependency on iPhone Mirroring and pyobjc, and that input goes through the clipboard with IME-safe semantics. It omits what happens to existing clipboard contents or whether text is required, which matter for a paste-based action.

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

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

Three short sentences with the key caveat (EXPERIMENTAL) front-loaded and no filler. Every clause carries information an agent needs before invoking.

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 typing tool, the description covers prerequisites and mechanism but leaves gaps: whether the single parameter is mandatory, what the clipboard side effect is, and what the tool returns. There is no output schema to fill those gaps.

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

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

Only one parameter ('text') at 0% schema description coverage, so the description must compensate. 'Type text via the clipboard' implies the parameter is the string to insert, but it never states this explicitly or whether it is required (schema says required: 0, which is ambiguous).

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

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

States a concrete verb ('Type text') plus the delivery mechanism ('via the clipboard') and the target environment ('Needs iPhone Mirroring'), so the agent knows this types into the mirrored iPhone rather than the host. It does not explicitly name how it differs from mac_type or browser_type, leaving that separation 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 description gives prerequisites (iPhone Mirroring, pyobjc) but says nothing about when to choose this over mac_type, browser_type, or phone_key for things like special keys or IME input. No exclusion conditions or alternative routing are offered.

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