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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether the tool waits for the element to appear, scrolls it into view, what happens on timeout, or whether the click fails silently. For an action tool with zero annotation coverage this 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?

Two compact sentences with the core action front-loaded and no filler. The selector syntax note is mildly redundant with the schema, keeping it just below the top score.

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 the interaction contract — waiting/retry behavior, failure modes, and what the preview vs editor frame distinction means in practice. It supplies none of that, leaving an agent to guess how a click resolves.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates the schema's selector note ('CSS selector or text=...'), adding only a fuller visible-text example; nth, frame, and timeout are left entirely to 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?

Clear verb+resource: 'Click an element in the live preview (or editor chrome).' An agent can distinguish this from siblings like perch_type or perch_press. It doesn't name those siblings explicitly, so it stops short of a 5.

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

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

The parenthetical '(or editor chrome)' implies the two target contexts, but there is no when-to-use guidance, no mention of prerequisites (e.g. page must be loaded/started), and no routing to alternatives such as perch_type for text entry or perch_press for keys.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the content of the read but says nothing about side effects (the 'clear' option mutates state), volume/truncation limits, or whether output is bounded across frames, which matters because errors are captured 'from every frame'.

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 that names the resource first and then enumerates the returned sources. No filler or repetition, though it slightly overpacks the return-value detail into the purpose 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 simple one-parameter read tool with no output schema and no annotations, the description adequately conveys what comes back. It is still incomplete on the mutation risk of 'clear' and on the relationship to perch_errors, which an agent needs to pick the right tool.

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

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

Schema description coverage is 100% and the single 'clear' parameter is already documented in the schema, so the baseline is 3. The description adds no meaning beyond that and never references the clear-after-read behavior.

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 clear verb+resource ('Read the console') and specifies the exact data sources it returns (the #console-output panel plus buffered console and runtime errors). It does not, however, differentiate itself from the sibling 'perch_errors', which plausibly covers the same runtime-error surface.

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 says what the tool reads but gives no when-to-use guidance, no exclusions, and no routing to alternatives such as perch_errors or perch_read. An agent must infer the distinction from the name alone.

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

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

With no annotations, the description carries the full burden and does disclose one meaningful trait: the copy is byte-exact, i.e. non-transforming, and it mutates the destination pane. It omits failure behavior (out-of-range lines, missing destination pane), and it does not clarify the model/output pane model even though that is central to how the copy behaves.

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 operation and scope, and the placement nuance is parenthetical rather than buried in a second paragraph. No filler; it could be slightly tighter by mapping directly to the pane parameters.

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

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

For a five-parameter mutating tool with no annotations and no output schema, the description is thin: it never explains what 'model' vs 'output' panes mean, what line indexing (1-indexed) implies, or what the call returns. An agent must reconstruct the pane concept entirely from the enum values.

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 80%, so the schema already documents startLine, endLine, afterLine, and the pane enums, which puts the baseline at 3. The description adds the conceptual notion of a destination pane and the append-vs-insert choice, but fromPane has no schema description and toPane's 'Default fromPane' text is ambiguous, and the description does not resolve that.

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 (copy) and resource (source lines) with the destination and an explicit qualifier 'byte-exact', which distinguishes it from transforming siblings like perch_edit, perch_patch, or perch_write. It stops short of naming a sibling alternative directly, so it lands just below the top band.

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 clarifies placement mechanics ('after a target line, or append') but says nothing about when to choose this over perch_edit, perch_patch, or perch_write, nor any prerequisite such as needing a valid destination pane sourced from perch_read. No when/when-not guidance is present.

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 one real behavioral trait – that a Yjs settle runs by default so the edit persists across reload – which adds meaning beyond the schema. However, as a mutation tool it says nothing about failure modes (e.g., no-match behavior), permissions, or reversibility, so the disclosure is partial.

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 the core operation front-loaded and the persistence note second. No filler, though 'surgical' is slightly promotional rather than informative.

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?

Six parameters, a mutation operation, no annotations, and no output schema – the description is thin for that complexity. It omits prerequisites, what happens when the target string is absent, and any error/response context, leaving an agent without enough to call it safely under edge conditions.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including nth, pane, settle, and replaceAll. The description adds only the rationale for the settle default ('survives a reload') and no syntax or format detail for oldString/newString. Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'find/replace in a pane'. An agent grasps the operation immediately, but the description never distinguishes it from siblings like perch_patch or perch_write, which occupy similar edit space. Clear purpose, no 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?

There is no explicit when-to-use guidance and no mention of when to prefer this over perch_patch (also an edit tool) or perch_write. The agent must infer the scenario from the phrase 'find/replace' alone, with no exclusions or alternatives named.

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

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

With no annotations, the description carries the full disclosure burden. It does reveal meaningful behavior: errors are buffered (persistent state), three distinct sources are merged, and clear:true resets the buffers — a mutating side effect. It stops short of describing the response shape or what happens if buffers are empty.

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 zero waste: the first enumerates the three error sources, the second covers the one option. Front-loaded and complete.

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-optional-parameter tool with no output schema, the description adequately covers sources and buffer semantics. The main omission is any hint at the returned structure or ordering of the aggregated errors.

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

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

Schema description coverage is 100%, so the single 'clear' parameter is already documented as 'Clear buffers after reading. Default false.' The description adds timing context ('after a fix') but no new syntax or format detail, so it sits at the high-coverage baseline.

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

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

States a specific purpose — aggregating editor syntax errors, buffered runtime/page errors, and console tail into one call. It even names the underlying API (window.getEditorSyntaxErrors). It does not, however, distinguish itself from the sibling perch_console, whose territory the 'console tail' overlaps.

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 framing 'Error triage in one call' implies a diagnostic context, and it advises 'Use clear:true to reset buffers after a fix.' But there is no explicit when-to-use-this-vs-perch_console guidance and no exclusions, leaving the choice between overlapping tools 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 are provided, so the description carries the full disclosure burden. It states the return ('its value') and the frame default, but says nothing about executing arbitrary code in the page context, any side effects, permissions, or failure behavior. For a code-evaluation tool this is a significant 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 tight sentences with no filler. The core action is front-loaded and the frame guidance follows immediately, so an agent can act on the first clause alone.

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

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

There is no output schema, and the description does cover the return shape ('its value') reasonably. Still, with no annotations and no disclosure of execution context, side effects, or error behavior, it is adequate but leaves notable gaps for a code-execution tool.

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

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

Schema coverage is 100% and both parameters are documented there, but the description adds real meaning the schema lacks: it clarifies what 'preview' actually refers to (the running generator) and when to pick 'editor'. That is value beyond the bare enum labels.

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: 'Run a JS expression and return its value.' This clearly distinguishes eval from read-oriented siblings like perch_read or perch_console, though it never names an alternative explicitly. The core purpose 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?

The description explains the frame default ('preview') and when to override it ('editor'), which is genuine usage guidance. However, it gives no context on when to reach for perch_eval versus adjacent tools like perch_console, perch_read, or perch_grep, so selection guidance is only partial.

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 does add real behavioral context: only public generators are fetchable, and the result is written to local files across two artifacts. However, it omits file overwrite semantics, whether credentials/permissions are needed, and any failure behavior when the generator doesn't exist.

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, zero filler: the action and payload are front-loaded, and the alias relationship follows. Everything stated earns its place.

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

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

For a simple two-parameter read-and-write-to-disk tool with full schema coverage and no output schema, the description covers action, target content, and destination. The remaining gap is the alias relationship: it never explains why an agent would choose this over perch_pull, which is material when both are exposed.

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

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

Schema description coverage is 100%, so the schema already documents both 'name' and 'path'. The description adds only that content lands in local files, loosely mapping to 'path', but gives no naming/format convention for the path hint or what 'name' accepts. Baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb (fetch) and resource (a public generator's source), and even enumerates the payload pieces (modelText + outputTemplate) plus the destination (local files). It distinguishes itself from generic siblings, but the 'Alias of perch_pull' note leaves the question of how this differs from perch_pull (scope, target, precedence) unresolved.

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?

Naming perch_pull as an alias implies the two are interchangeable, which is usable guidance by inference, but there is no explicit when-to-use, when-not-to-use, or selection criterion between the two supposedly identical tools. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the return format ('matching lines with optional context') and 'search' strongly implies a read-only operation, but it does not explicitly state side-effect absence, permissions, or performance characteristics.

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

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

Two sentences with no wasted words; the core operation and return behavior are front-loaded. It is appropriately sized for a simple search 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?

There is no output schema and no annotations, so the description must explain return values; it does so briefly by stating matching lines with optional context. The schema covers parameter details, but the description could mention result limits or line numbering for fuller completeness.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the input schema. The description only echoes the pane-omission behavior and optional context, adding no format, syntax, or default details beyond what the schema provides.

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

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

The description states a specific verb (Regex search) and resource (pane), with scope covering one or both panes. It is clear enough to distinguish from generic read or edit tools, but it does not name or contrast with sibling tools such as perch_read or perch_outline.

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

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

It gives a usage condition for the pane parameter ('or both if pane omitted'), which implies when to omit it. However, it offers no explicit guidance on when to choose this tool over alternatives like perch_read or perch_outline, leaving selection mostly 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 are provided, so the description carries the behavioral burden. 'List' conveys a read-only, non-destructive operation, and 'with sizes' hints at the return content, but it does not explicitly state safety, permissions, or side-effect absence. For a zero-parameter listing tool this is adequate but minimal.

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

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

A single front-loaded sentence with no filler. It states the action, scope, and return detail in one pass, earning every word.

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, simple listing tool with no output schema, the description is nearly complete: it identifies what is listed and mentions that sizes are included. It could go slightly further in describing the return format or clarifying 'srcManifest' for an unfamiliar agent, but no critical invocation detail is missing.

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

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

The tool takes zero parameters, and the schema is correspondingly empty. Per the rubric, zero parameters yield a baseline of 4; there are no parameter semantics needing further explanation.

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

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

The description names a specific verb ('List'), a precise resource ('src/ files in the generator's srcManifest'), and an additional output dimension ('with sizes'). It is easily distinguished from siblings like perch_src or perch_upload_src, which operate on source files rather than listing the manifest.

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 perch_src or perch_grep, nor any exclusions. The phrase 'all src/ files' implies scope but does not constitute usage 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, and it does most of the work: it discloses that navigation is top-level only, that it waits for a Cloudflare challenge to clear, and that the editor must be reloaded afterward. It does not say whether navigating away discards current editor state, what the tool returns, or what failure looks like if the challenge never clears.

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 primary purpose is front-loaded, and the recovery procedure is sequenced clearly (visit top-level, let challenge clear, perch_start with force:true). The middle sentence is dense and runs long, but nearly every clause carries actionable information rather than filler.

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

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

For a two-parameter tool with no annotations and no output schema, the description supplies the essential context: scope (top-level only), the CF challenge behavior, and the recovery workflow. The remaining gap is the effect on existing editor/page state and error behavior when the challenge does not clear.

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

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

Schema coverage is 100%, so url and timeout are already documented in the schema. The description restates the challenge-wait semantics that the timeout parameter description already carries, adding no new syntax or format detail beyond that. Baseline 3 is appropriate.

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

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

States a specific verb and resource: navigate the whole editor PAGE to an https:// URL at top level. It also implicitly distinguishes itself from perch_start by positioning navigation as the recovery step that precedes a forced reload, so an agent can separate it from siblings without reading 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?

Gives an explicit when-to-use scenario (CF-blocked embed/subframe such as text-generation.perchance.org under ai-text-plugin) and the follow-up alternative (perch_start with force:true), plus the secondary case of loading pages for inspection. It omits any when-not guidance, e.g. preferring subframe-level navigation or when perch_refresh is the better choice.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses what it returns (declarations, not full text) and its use case, and "map" implies a read-only orientation operation. It omits behavioral detail like the default 400-entry truncation, whether output listing is capped, or scope limits over a large file.

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

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

A single front-loaded sentence with zero filler. The core function is stated first, followed by the orienting rationale. 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?

This is a low-complexity read tool with full schema coverage, and the description conveys enough to call it correctly. Without an output schema, it partially explains the return shape (a line map), though it stops short of detailing format or truncation.

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

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

Schema coverage is 100%, so both parameters (pane enum and limit) are already fully documented in the schema. The description adds no parameter-level meaning (e.g., what pane 'model' vs 'output' implies). Baseline 3 is appropriate when the schema does all the work.

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 output type (a line map of function/class/const declarations) and its purpose (orienting in a large file). An agent can tell it produces an outline rather than file contents, but it never names a sibling it is not.

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?

"Orient in a 40k-line file without reading it all" implies a when-to-use context (large file, reconnaissance before reading). However, it does not name alternatives such as perch_read or perch_grep that an agent should pick instead when it needs actual content or pattern search.

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

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

With no annotations, the description carries the full behavioral burden yet discloses almost nothing: it doesn't confirm this is a mutation, doesn't state atomicity (all-or-nothing vs partial apply on failure), what happens when oldString is not found, or any permission/auth requirements. 'Surgical changes' hints at precise string replacement but is not elaborated.

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 the core purpose front-loaded and the change shape given second. No filler, though the field list is a bare enumeration rather than prose that earns its place.

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

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

For a mutation tool with no annotations, no output schema, and only 50% schema coverage, the description is too thin. It omits failure behavior, atomicity, what panes model/output represent, and the sync implications of settle, leaving an agent under-informed before invoking.

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

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

Schema coverage is 50%; the top-level 'settle' param is already documented in-schema. The description lists the nested change fields ({pane, oldString, newString, replaceAll?, nth?}), which the schema names but does not describe, so it marginally aids understanding of the array item shape without explaining the semantics of nth or replaceAll.

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 (Apply) and resource (multiple surgical changes) plus a scope qualifier ('in one call'). This implicitly distinguishes it from the single-edit sibling perch_edit, though it never names that sibling explicitly.

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

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

The phrase 'multiple surgical changes in one call' implies the batching use case, so an agent can infer it is preferable to repeated single edits. However, there is no explicit when-to-use/when-not guidance and no named alternative to steer toward.

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 meaningful trait: input is delivered to whatever element currently holds focus rather than to a target the caller names. Beyond that it says nothing about whether the press triggers navigation, whether combos are supported, or what is returned on failure.

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

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

A single short sentence, front-loaded with the verb and the scope, with zero filler. Nothing in it is redundant padding.

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, with two fully documented parameters and no output schema, so the description is close to sufficient. It nonetheless omits the focus prerequisite and any indication of response behavior, which are the main things an agent needs to sequence this call correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including 'Key name, e.g. \'Enter\''. The description's example keys (Enter, Tab, Escape) merely restate the schema's own example, and the 'frame' parameter (preview/editor) is not addressed at all, so the baseline of 3 is correct.

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) applied to a specific resource (a named key) and names the target ('the focused element'), so the agent immediately knows this is a keyboard-input tool rather than text entry. It does not explicitly contrast itself with the similar sibling perch_type, which types text, so sibling differentiation is left to inference.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of the prerequisite that something must already be focused, and no routing to the adjacent tools (perch_type, perch_click). 'Focused element' faintly implies a precondition but nothing is stated explicitly.

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 ~1.2s latency, no auth/collab key requirement, that it writes files locally, and independence from perch_start. It omits failure modes and overwrite/refresh behavior, which keeps it from 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?

Front-loads the key differentiator ('BROWSER-FREE code access') and packs timing, constraints, and workflow into three dense sentences. The em-dash clauses are information-rich rather than filler, though slightly crowded.

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

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

For a 2-param tool with no output schema or annotations, it covers what is fetched, where it lands, timing, and prerequisites. Return-value details are unnecessary since the payload is written to files, but overwrite/refresh semantics remain 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 100%, so both params (dir, name) and their defaults are already documented in the schema. The description adds no syntax or default behavior beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (Fetch) plus the exact resources (modelText/main.pjs, outputTemplate/index.html) and the side effect (write to local files). An agent can distinguish it from siblings like perch_fetch_generator or perch_start 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?

Gives clear context: browser-free, no Cloudflare, no collab key, and explicitly 'Works without perch_start', plus the downstream workflow ('Grep/read those files directly'). It stops short of naming an explicit alternative or a when-not-to-use condition versus perch_fetch_generator.

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 source is the LIVE editor and the return format is 1-indexed numbered lines, but it omits session requirements, error behavior, and confirmation that it is a read-only operation.

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

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

A single front-loaded sentence with no filler. Every phrase contributes: the action, the source, the pane identifiers, and the output shape.

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

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

For a simple read tool with full schema coverage and no output schema, the description explains the return format well enough. The absence of annotations means some safety context is left implicit, but an agent can call this correctly with the given information.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by mapping model to main.pjs and output to index.html, clarifying the enum values beyond the schema's terse 'Default output' label.

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 (Read) and resource (a pane from the LIVE editor) and maps the two pane values to their files. It does not distinguish itself from siblings like perch_outline or perch_grep, so it falls 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?

No when-to-use guidance, no alternatives named, and no exclusions. The description never explains when this tool is preferable to perch_outline, perch_grep, or perch_pull.

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. 'Hard-reload' usefully signals a cache-bypassing reload and 'new console lines' implies an incremental console diff, but it does not say whether the reload discards in-page state, whether the preview must already be running, whether the call blocks until load completes, or whether it mutates anything.

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 action first and the returned diagnostics second. No filler, nothing redundant.

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 with no output schema, the description tells the agent what the call produces (three categories of diagnostics) and that it reloads the preview. The remaining gaps — blocking behavior, session prerequisites, and how it relates to the dedicated console/error tools — are secondary but not trivial given 26 siblings.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter detail because there is none to add.

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 ('hard-reload') and resource ('live preview') plus the payload it reports (syntax errors, runtime errors, new console lines). It is clearer than most siblings, though it does not distinguish itself from perch_console/perch_errors, which appear to surface overlapping information.

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: reloading after edits to surface errors. There is no explicit when-to-use, no statement of prerequisites (e.g. an active preview session), and no routing advice toward perch_console or perch_errors, which are the obvious alternatives for reading the same diagnostics.

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 dual nature of the operation (mutates the live preview AND returns the iframe rect), but says nothing about permissions, whether resizing persists, or how it interacts with other preview state.

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

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

A single compact sentence, front-loaded with the primary verb and effect, with no filler or redundancy.

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

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

For a two-param tool with defaults, the essentials are present, but there is no output schema and the description does not specify the shape of the reported rect or the units of width/height. Adequate but with clear gaps.

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

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

Schema coverage is 100%, but the schema descriptions only give defaults ('Default 1500'/'Default 950') without units, and the tool description adds no meaning beyond echoing that a rect is produced. Baseline 3 for full schema coverage with no extra semantic value in the description.

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

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

States a specific verb ('Resize') and resource ('the live preview'), plus a secondary effect ('report the iframe rect'). An agent can tell what it does, though the description does not relate it to any sibling (e.g. perch_shot/perch_navigate) even though none of them resize.

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 when-to-use condition, no prerequisites, and no mention of alternatives. The agent must infer that this is a setup step before capturing or inspecting a preview; the description gives none of that context explicitly.

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 falls short. It does not disclose that the tool writes a file to disk (only the `path` param hints at it), what happens when `path` is omitted, whether the editor must be running, or any permission/side-effect profile.

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?

Extremely tight, front-loaded with the tool's action and then the parameter meaning in one clause. Nothing is padded, though the telegraphic fragment style borders on under-specification rather than true conciseness.

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

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

No output schema and no annotations, so the description should explain the return artifact (file path, image bytes, or inline result) and the default capture destination. It omits all of this, leaving the agent unsure what calling the tool actually produces.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: the schema only says `what` defaults to "editor", whereas the description explains that 'editor' captures the whole editor page and 'preview' captures the running generator iframe. It adds nothing for `path`, however.

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

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

The description names the resource (a screenshot) and, via the `what` values, the two capture targets (whole editor page vs running generator iframe). It is a fragment rather than a verb+object sentence, and it does not differentiate from the sibling `perch_snapshot`, which an agent could easily confuse with a screenshot.

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

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

The two `what` values are explained, which implies the capture-scope choice, but there is no explicit when-to-use guidance and no mention of alternatives like `perch_snapshot` or `perch_console` for visual inspection.

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 burden. It discloses useful behavior: output is a text list of visible interactive elements with CSS selectors, scoped to the live preview, implying a non-mutating read. It does not state prerequisites (a started/running preview), whether results reflect off-screen or hidden elements, or any size/performance limits, leaving real gaps for an annotation-free 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 tight sentences, front-loaded with the core action and followed by the differentiating usage rule. Every clause earns its place; nothing is restated from the name or schema.

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

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

There is no output schema, so the description usefully compensates by describing the return shape (visible interactive elements, each with a CSS selector). With three optional, fully schema-documented parameters and no annotations, the only meaningful omission is the prerequisite that a live preview must exist and how frames interact with it.

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

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

Schema description coverage is 100%, with frame (enum), limit, and filter all documented in the schema, so the baseline is 3. The description adds no parameter-level detail beyond the schema — it never mentions frame selection, the 250 default limit, or label/tag filtering — so it neither helps nor hurts.

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 (list) and resource (visible interactive elements: buttons/inputs/links) scoped to the live preview, and adds the returned artifact (a ready-to-use CSS selector per element). It also distinguishes itself from the screenshot sibling ('instead of screenshots'), so an agent can route between perch_snapshot and perch_shot without opening 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?

'Use this instead of screenshots to find what to click' gives explicit when-to-use guidance and names the alternative approach implicitly (screenshots = perch_shot), and pairs naturally with perch_click/perch_type downstream. It stops short of stating exclusions or prerequisites (e.g. preview must be running via perch_start), so it is clear context rather than 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?

No annotations are provided, so the description carries the burden, but it does disclose useful context: the file is resolved from the generator's srcManifest and fetched via the CDN. It still omits permissions, error behavior (e.g. missing path), and return format.

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 the operation and the resolution mechanism front-loaded and zero 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 one-parameter read tool with no annotations or output schema, the definition is minimally adequate but does not describe what is returned (file contents? manifest entry?) or failure modes when a path does not exist.

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

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

Schema coverage is 100%, so the single path parameter is already documented with an example. The description adds only the resolution context (srcManifest/CDN) rather than path syntax or constraints, matching the baseline for fully-covered schemas.

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 (Read) and resource (a src/ file) and adds the resolution source (generator's srcManifest via CDN). This distinguishes it somewhat from a general perch_read, though it does not explicitly name the sibling it is not.

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 and no comparison to alternatives like perch_read, perch_list_src, or perch_fetch_generator. The agent must infer the routing from the description alone.

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

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

With no annotations the description carries the full burden and does well: it discloses the browser launch side effect, automatic Cloudflare handling via a '4-step escalation ladder', idempotent re-call behavior, and the ownership prerequisite for non-collab mode. It stops short of describing failure modes or what a successful start 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?

Three tight sentences, front-loaded with the core action, followed by the two operational facts an agent most needs (Cloudflare auto-handling, idempotency). Zero 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 7-param, no-annotation, no-output-schema tool, the description covers launch, stealth/Cloudflare behavior, idempotency and collab prerequisites. Return value and error behavior are unspecified, which is the main remaining gap since there is no 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: collabKey omission semantics ('must own the generator') and the no-op/force relationship on re-call. These go beyond the per-field schema text.

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: 'Start the Perchance editor session' plus the concrete actions (launch browser, load generator with collab key, ready to edit). It is clearly a session-bootstrap operation that contrasts implicitly with perch_navigate/perch_refresh, though no sibling is named explicitly to sharpen the distinction.

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?

Explains when re-calling is appropriate ('fast no-op' with same generator/collabKey) and the collabKey omission case for non-collab edits. It does not name an alternative tool for the already-running case, but the idempotency note largely covers the decision 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?

No annotations are provided, so the description carries the full burden, and it does disclose the reported facets (save state, syntax errors, collab sync, line counts, engine, CF status, buffered counts). However it never states that this is a read-only, side-effect-free observation, nor how expensive it is or whether it changes state. Useful content, but the behavioral profile is incomplete for a zero-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?

A single sentence with the verb and resource front-loaded, followed by a compact enumeration; every listed item corresponds to returned data and earns its place. Minor deduction for jargon ('CF status') that is not self-explanatory.

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

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

With no output schema, the description effectively serves as the return-value contract by naming each reported field, which is the right thing to do here. It is nearly complete for a zero-param read tool, lacking only an explicit read-only/side-effect statement.

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 schema baseline of 4 applies and there is nothing for the description to compensate for. No parameter semantics are needed or 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 opens with a specific verb+resource ('Report live editor state') and then enumerates exactly which facets are reported. That enumeration makes the tool distinguishable from siblings like perch_console, perch_errors and perch_outline, which cover subsets of this data. It stops short of naming 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?

Usage is only implied: an agent can infer this is the general health/diagnostics check from 'live editor state', but there is no explicit statement of when to prefer this over perch_console or perch_errors, and no prerequisites or exclusions. Adequate but with a clear gap given the crowded sibling set.

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. "Close the browser session" implies teardown, but it does not say what state is destroyed, whether the call is idempotent when no session exists, whether it errors, or what "resume" actually preserves — that word alone is ambiguous about persistence.

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

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

Two short sentences with zero filler, and the primary action is front-loaded before the follow-up instruction. Nothing in the text is redundant with the name.

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 teardown tool with no output schema, the description covers the essential action and the restart path. It falls short on the one thing an agent would genuinely want to know before tearing down a session — what happens to in-flight state and whether the close is destructive or reversible.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate; the empty schema is fully consistent with the stated action.

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

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

States a specific verb (close) and resource (browser session), which cleanly separates it from the sibling family (read, edit, navigate, etc.). It references perch_start for the inverse operation, so the pairing is inferable, though it never explicitly contrasts itself with other lifecycle siblings like perch_status or perch_refresh.

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?

"Call perch_start again to resume" names the follow-up tool, which gives a partial sense of when this tool sits in a workflow. However, it never states the condition for calling it (session no longer needed, done browsing, cleanup after errors) nor any when-not 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 behavioral burden, and one sentence does not cover it. It never says whether existing content is cleared, whether the element is focused first, whether it waits for the element to appear, or how failures surface.

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 filler. It is appropriately sized, though minimal to the point of under-specification for a five-parameter mutation 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?

Five parameters, no annotations, and no output schema leave the description responsible for behavioral context it does not provide. An agent still cannot tell what typing does to existing content or what a call returns, so it is incomplete for the tool's complexity.

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

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

Schema coverage is 100%, so all five parameters (text, frame, submit, timeout, selector) are already documented in the schema. The description's only added hint is the '(or editor chrome)' scope, which maps to the frame parameter but adds little beyond the enum already given.

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 (type) and resource (text into an element), plus scope (live preview or editor chrome). An agent can reasonably distinguish it from perch_click and perch_press, though it never explicitly names those siblings as 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 when-to-use guidance at all. The description does not say when to reach for perch_type versus perch_edit, perch_press, or perch_click, nor any prerequisites such as the element needing to be focusable or the preview being started.

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 so well: it discloses the injection mechanism (DataTransfer, no OS dialog) and the lifecycle state transition (lands in the editor src store as 'saved', becomes public only when the owner saves). This is meaningful behavioral context beyond the schema, though it omits permission/auth requirements and failure behavior.

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

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

Two tight sentences that are front-loaded with the core action and follow immediately with the mechanism and post-action state. Zero wasted words.

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

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

For a file-upload tool with no output schema and full schema coverage, the description supplies the key non-code context an agent needs (mechanism and when the file becomes public). It is nearly complete, missing only auth/permission expectations and error handling.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, and the description adds no additional parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (upload) and target (a file into the generator's src/ via the editor's file panel), with a clear mechanism. It is distinguishable from siblings like perch_write or perch_src by naming the panel/DataTransfer route, though it does not explicitly contrast with those siblings.

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

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

The context implies when this is useful (placing a file into the generator src store), but there is no explicit guidance on when to choose this over perch_write, perch_src, or perch_patch, nor any stated prerequisites. Usage is only implied.

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 burden. It usefully discloses the gone:true inversion and that waiting happens in the preview frame, plus workflow placement. However, it never says what happens when the timeout elapses (error vs. empty return) or that the call blocks, which are the key behavioral traits for a wait primitive with no output schema.

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

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

Two short sentences, no filler, with the primary behavior front-loaded and the usage cue second. Every clause earns its place.

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

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

For a 5-parameter tool with no annotations and no output schema, the description covers the core purpose and usage but omits the failure mode on timeout and any indication of the return value. The schema documents the inputs, so the definition is workable but leaves the agent guessing about outcomes.

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

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

Schema description coverage is 100% and every parameter (gone, text, frame, timeout, selector) is documented in the schema itself. The description only restates the gone flag and the selector/text target, adding no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (wait) and resource (selector or visible text) plus the inversion case (gone:true) and the scope (preview). An agent can tell this is a synchronization primitive rather than a read/action tool. It does not explicitly name a sibling, but the verb+resource is unambiguous.

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

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

'Use after a click/edit before asserting' gives a concrete triggering context, which is exactly the workflow an agent needs. It stops short of naming alternatives (e.g. perch_snapshot or perch_read for immediate checks) or stating when not to use it, so it is clear context without 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 it does disclose the key behavioral trait: this is a destructive wholesale overwrite of the pane's document. It omits everything else an agent would want — reversibility/undo, whether existing history is preserved, permission or session requirements, and return behavior.

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

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

A single sentence with zero filler, and the destructive scope ('entire') is front-loaded where an agent will see it first. Nothing to trim.

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, fully documented mutation tool with no output schema and no annotations, the description covers the core action but is thin on the two things the structured fields cannot supply: sibling selection guidance and behavioral/safety traits.

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

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

Schema description coverage is 100%, so panes, settle, and content semantics are already documented in the schema. The description adds no syntax, format, or default-caveat information beyond that, so baseline 3 applies.

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

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

States a specific verb ('Replace') and resource ('an entire pane's document'), which is enough for an agent to know this is a full-document overwrite. It does not, however, name or contrast with the obvious siblings perch_edit/perch_patch/perch_copy_lines that also write content, so differentiation is only implicit.

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

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

The word 'entire' implies the when-to-use condition (whole-document replacement rather than incremental editing), but no alternative is named and no prerequisites or exclusions are stated. Usage is inferable rather than explicit.

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