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

With no annotations, the description carries the full burden and does so richly: it discloses that write policy is enforced at the network layer, exactly what each mode blocks/allows, that readPosts is user-named only, that role attaches are refused without a saved login, and that dedup='judge' sends evidence to a third-party provider. This is behavioral context well beyond the schema.

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

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

Front-loaded with purpose and prerequisites, and no sentence is pure filler. However the write-policy sentence is an extremely long run-on cramming four modes and their exceptions into one breath, which hurts parseability even though the content is valuable.

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 21-parameter tool with no annotations and no output schema, the description covers the critical routing decisions (mode, role, session, dedup) thoroughly and leaves the mechanical params to the 100%-covered schema. It does not describe the attach result or what a successful attach returns, which is the main residual gap.

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 parameters and baseline is 3. The description adds meaning on the highest-stakes params: it explains the mode taxonomy (which the schema delegates to it), the role/session interaction and multi-role concurrency, and the readPosts restriction — genuine added value over the enumerated values.

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 ("Launch a browser and attach to a running web app") and separates itself from siblings like scout_login, scout_navigate and scout_run_plan. An agent can immediately tell this is the entry/attach tool.

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

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

Explicitly directs the agent to call scout_playbook first when new to the conversation, and gives conditional selection rules for every mode: observe for real data, read-only as default, safe-write for create/edit flows, destructive only on user-confirmed disposable envs. Names alternatives (storageStatePath vs role) and preconditions.

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 say what happens when there is no history to go back to, whether the page is reloaded/re-verified, whether in-page state survives, or whether the tool waits for load — all material for a navigation action in a test harness.

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, action first, with the parenthetical earning its place by giving the testing rationale. No 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 no-annotation, no-output-schema navigation tool with four well-documented params, the definition is minimally adequate but silent on outcome (no return shape, no statement of what the agent should do if history is empty). It is callable but not fully self-explanatory.

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 task, leave, session and objective in depth. The description adds nothing about any parameter; baseline 3 applies 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 verb and resource: 'Go back in browser history', with a parenthetical scoping it to back-button resilience testing. That is enough to tell it apart from scout_navigate and scout_click, though it never names the sibling it complements.

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 '(tests back-button resilience)' implies when this tool is relevant, but there is no explicit when-to-use statement, no exclusions, and no mention of scout_navigate as the forward-navigation counterpart.

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 output format (PNG), content (element bounds plus margin), and write location (.scenescout/captures/), but does not address permissions, error cases, overwrite behavior, or what 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?

Three sentences, front-loaded with the core action and output path. The ref-sourcing instruction and the design-audit exclusion each earn their place, with no wasted wording.

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

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

For a no-output-schema, no-annotation tool with five parameters, the description covers purpose, element selection, output location, and sibling routing well. It does not state what the tool returns (e.g., a capture key), though the schema's key parameter implies a return artifact.

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 five parameters are already documented in the schema. The description reinforces that ref comes from the latest scout_snapshot and adds conceptual meaning to margin, but does not add syntax or constraints 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?

States a specific verb and resource: save a PNG of ONE element from a real screenshot, with scope (bounds plus margin) and output location (.scenescout/captures/). It distinguishes itself from the full-page sibling scout_screenshot by emphasizing 'ONE element' and from scout_design_audit by name.

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?

Tells the agent to supply the element's ref from the latest scout_snapshot, and explicitly routes design judgment to scout_design_audit. It implies the contrast with full-page scout_screenshot via 'ONE element' but does not name that alternative directly.

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 double-submit probe semantics, that the result explicitly reports whether duplicates fired, and that oracle violations are returned. It omits behavior on a stale ref or a ref missing from the snapshot, which is the main residual gap for a mutation 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?

The core action is front-loaded in the first sentence, and the detail sentences earn their place by explaining the probe. The middle sentence is a dense run-on with stacked em-dashes, so it is slightly heavier than necessary.

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

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

For a tool with no annotations and no output schema, the description explains both the action and the return semantics (outcome, duplicates, oracle violations), which is enough to call it correctly. What is missing is prerequisite/staleness handling for the ref and any error 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 100%, so baseline is 3, but the description adds genuine interpretive meaning for the `clicks` parameter — explaining that two fired requests indicate an unguarded control — beyond the schema's terse '1 = normal; 2-3 = rapid repeated clicks'.

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 precise verb+resource: clicks an element identified by its ref from the latest scout_snapshot, and notes the return payload (outcome plus oracle violations). It fails to explicitly separate itself from keyboard-style siblings like scout_press or scout_select, so an agent must infer the distinction from the 'ref' target.

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 operative rule for the probing mode: use clicks=2/3 on every important submit/create button once, and it explains what a duplicate response implies. It does not, however, say when to prefer this tool over siblings such as scout_press or scout_type, so tool-choice guidance is incomplete.

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 delivers: it discloses persistence, default/all behavior, lane-close refusal, and the destructive consequence of force. It also mentions that refusal names every such lane, so the agent knows what to expect. No contradictions.

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

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

Three sentences, front-loaded with the core action and default behavior. The lane sentence is long but carries necessary exception logic; no filler or repeated schema content.

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 state-changing tool with no annotations and no output schema, it covers the main behaviors, including edge cases (lanes, force). It doesn't describe return values or error handling beyond the refusal, but that's a minor gap for a close operation.

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 already documents all three parameters at 100% coverage, so the baseline is 3. The description adds operational context: when to use all, what force destroys, and the default session behavior. This is meaningful added value, though the schema itself already covers force well.

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

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

The description opens with a specific verb and resource: 'Close a session's browser.' It also states the key side effect (memory persists on disk) and distinguishes default, specific, and all sessions, which separates it from sibling tools like scout_session or scout_snapshot.

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 explicit operational guidance: default session, session parameter for a specific one, and all=true for multi-role runs. It also explains when not to close—lane sessions awaiting acceptance—and directs the agent to scout_lane_report for folding. It doesn't enumerate all alternatives, but the key routing 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?

With no annotations, the description carries the full burden and does substantial work: it discloses the default scope in parallel runs, the session-vs-project scoping behavior, and that each form/route is tagged with the sessions that saw it. It does not state read-only safety or return format, but for a read-only coverage query the parallel-run semantics are the key behavioral fact and they are covered.

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

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

Front-loaded with what the tool shows, but the prose is long and dense, with nested clauses such as 'which options of a dropdown used this run no session has chosen yet' that are hard to parse. It also duplicates the schema's scope explanation, so not every sentence earns its place.

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

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

No output schema exists, so the description must characterize returns, and it does enumerate the coverage categories reported. Combined with the parallel-run scoping explanation and the documented defaults, an agent has enough to call it correctly; only the output shape (format, grouping) is left implicit.

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 defines both parameters thoroughly, including the default rule for `scope`. The description largely restates that (session vs project) and adds only the rationale ('so one lane is not handed another's gaps'), which is marginal value over the structured field.

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 ('Show exploration coverage') and then enumerates exactly what is shown: visited states, unexercised elements, unselected dropdown options, unsubmitted blank-field forms. An agent can distinguish it from status/report siblings by content, though no sibling is named to sharpen the contrast.

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 when-to-use context: 'Use to decide where to explore next and when the level's budget is satisfied.' That is a concrete decision context, but no alternative tool is named and no explicit when-not condition is given.

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

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

With no annotations present, the description carries the full burden and delivers: it discloses side effects (records states into coverage memory), the safety profile ('Navigation-only — safe in read-only mode'), and the exact per-route signals returned (status, element count, oracle violations, dead-ends, auth-redirects, ERROR-VIEW/STILL-LOADING). This is unusually complete behavioral disclosure for an unannotated 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?

Front-loaded with the core action and scope in the first clause, then the output shape, then the routing guidance. The long parenthetical enumerating return signals is dense but each item earns its place; 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?

No output schema exists, and the description compensates by enumerating what the health summary contains, plus safety and coverage-memory side effects. Nothing an agent needs to call this correctly against its 35 siblings is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters, including the default-to-unvisited-routes behavior and the concurrent multi-session use of `session`. The description adds no parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('route sweep... visits each path') plus the default scope (all known routes not yet visited) and the return artifact. An agent can distinguish it from interactive siblings like scout_click/scout_navigate 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?

Explicitly says 'Use this FIRST for broad coverage; explore interactively only where it flags problems or where journeys matter,' giving both the when-to-use and the when-to-use-alternatives condition. This directly routes the agent between this bulk crawler and the interactive 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 full burden and does well: it discloses idempotent replacement semantics ('Recording the same criterion again from the same session replaces your earlier verdict'), the fact that link judgement is never word-matched, and that it 'Touches no browser.' It stops short of stating auth/permission needs or any failure/error 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?

Front-loads the core action and scope in the first clause, then layers the linkage rule, fail/not-tested requirements, and idempotency. Dense but all sentences earn their place; the parenthetical 'file them with scout_finding first' is well placed.

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 an 8-param, no-annotation, no-output-schema mutation of run state, the description covers prerequisites, verdict semantics, idempotency, and browser footprint. Only the return/confirmation behavior and any permission constraints are left unstated, which is a minor gap.

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 a baseline of 3 applies, but the description adds cross-parameter semantics the schema does not spell out: a 'fail' requires naming findings, 'not-tested' requires untestedBecause, and confidence must be an honest judgement rather than a match. That is genuine meaning beyond the field-level docs.

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 (record) and resource (one acceptance criterion of a ticket), names the exact scope, and ties the resource back to scout_tickets. It is immediately distinguishable from siblings like scout_finding or scout_note.

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 tells the agent when to use it (recording a pass/fail/not-tested verdict), the prerequisite ordering ('file them with scout_finding first'), which sibling produced the ticket (scout_tickets), and what happens on re-record from the same session. This goes well beyond implied usage.

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 and does a good job: it declares the audit is computed-style without screenshots, samples keyboard focus with 'real Tab presses', and lists both measurable defects and craft suggestions. It does not address side effects or permissions, but as a read-only audit the implied behavior is clear.

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 long but densely informative, with clear structure: purpose, defect types, suggestion types, summary, and usage note. It front-loads the core identity and every subsequent clause adds practical detail. A little trimming would be possible, but the length serves the complexity of the tool.

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

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

Given the tool has no output schema and no annotations, the description compensates well by enumerating what the audit detects, the structure (defects vs. suggestions vs. system summary), and how to use the results. It does not specify the exact return format, but the content coverage is sufficient for an agent to invoke it correctly.

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

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

The only parameter, session, is already fully documented in the input schema with clear guidance on when to pass it explicitly. The description adds no additional parameter semantics, which is acceptable because schema coverage is 100%.

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

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

The description opens with a specific verb and resource: a 'computed-style design audit of the current page', and explicitly distinguishes itself with 'WITHOUT screenshots'. It enumerates distinct audit categories (WCAG contrast, tiny targets, clipped text, etc.), making its purpose unmistakable compared to siblings like scout_screenshot or scout_scan.

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 clear usage context: 'Run once per representative page' and instructs that improvement-tier findings should be filed as ux-polish findings with concrete numbers rather than just as defects. It does not explicitly name alternative tools or exclusion criteria, but the context is specific enough to guide correct invocation.

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 automatic deduplication across runs, automatic capture of the recent action trace as the repro, and automatic capture of a picture (element `ref` or viewport) that is persisted for report.html and returned as an image. These are real side effects an agent should know about, though failure modes and any permission requirements are not covered.

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

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

It is a single dense paragraph, but it is front-loaded with the purpose, then behavior, then usage scope, and every clause carries information (dedup, repro capture, image, category examples). The heavy em-dash listing makes it slightly harder to scan than an ideally structured definition.

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 an 8-parameter, no-annotation, no-output-schema tool, the description covers purpose, side effects, return of the captured image, and filing conventions. It is close to complete; only edge details like severity semantics and error behavior are left to the schema.

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

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

Schema description coverage is already 88%, so the schema does most of the work, but the description adds meaning beyond it: it explains the `convention` field's special role (routed to a "Worth a look" section and not counted as a defect) and reinforces the `ref`/picture behavior. That is meaningful added value above the high-coverage baseline of 3.

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 precise verb+resource ("Record a structured finding") and enumerates what qualifies (crashes, UX issues, improvements), so the agent knows exactly what this tool produces. It does not explicitly name or contrast a sibling tool (e.g. scout_note) to disambiguate where else one might file an observation, 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?

"Use for anything worth reporting" followed by a concrete list of triggers (crashes, confirmed oracle violations, dead ends, confusing UX, permission leaks, missing testids, ux-polish) gives strong when-to-use guidance. There is also a when-not signal for the `convention` field ("Not for 'I could not tell'"), but no explicit alternative tool is named for cases this tool should not handle.

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 full behavioral disclosure responsibility. It explains that results are diffed against pre-hover state, unrelated text may be labelled, items are truncated to 300 characters, and hover does not count as exercising the element. This gives a clear and honest model of the tool's 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?

Three dense sentences with no filler: the first defines behavior and outputs, the second states a key caveat, and the third provides usage guidance. The most important information is front-loaded.

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

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

Despite having no output schema and no annotations, the description explains the result composition, truncation, and possible noise. Combined with complete parameter schema and explicit usage conditions, an agent has everything it needs to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%: both ref and session already have full descriptions, including the concurrency behavior of session. The tool description adds little per-parameter detail, but that is acceptable because the schema already handles parameter semantics.

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

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

The description names a specific verb and resource: hover an element by ref and report what it reveals. It enumerates concrete outputs (tooltips, new text, title attribute, aria-describedby) that clearly distinguish it from sibling tools like scout_click and scout_snapshot.

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

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

The description explicitly says to use it on badges, icons, truncated text, and error indicators before concluding an element 'does nothing', which is strong when-to-use guidance. It also notes that hovering does not count as exercising the element, implying it is not a substitute for interaction, though it does not name scout_click as the explicit alternative.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that it returns scout_login and scout_attach calls in order, falls back to returning questions for chat, never asks for a password, and touches no browser. These are meaningful behavioral facts beyond a simple 'ask questions' framing, though the return payload shape is only sketched.

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?

Purpose is front-loaded, but the middle sentence ('Where this client can show a form, the person answers there and this returns the settings to use: the scout_login and scout_attach calls, in order') is dense and runs on. The content earns its place, yet the phrasing could be tightened without loss.

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

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

With no output schema and no annotations, the description must explain what comes back, and it does: either settings (scout_login/scout_attach calls in order) or a list of questions. It also covers the no-password and no-browser guarantees. Only the exact response structure remains slightly underspecified.

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 there is a single optional parameter, so the schema already defines 'url' fully. The description adds only that the value pre-fills the form when the person has already stated the address, which is marginal beyond the schema text. 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?

The description gives a specific verb and resource ('Ask the start-of-run questions') and enumerates what those questions cover (address, sign-in, what to check, real data). It also situates the tool relative to siblings by naming scout_login and scout_attach as its outputs, so an agent can tell it is the setup/intake step. It stops short of an explicit 'use this instead of X' contrast, which keeps it from 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?

It states a clear triggering condition: use it 'when the person gave no settings.' It also distinguishes the two execution paths (form vs. chat fallback) and when each applies ('otherwise, or when they decline or close the form'). No explicit when-not is given, but the gating condition is unambiguous.

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 full behavioral burden and does so well: it discloses that the tool actually performs the journey by clicking, that shortcuts invalidate the measurement, what metrics are returned, and how to interpret abandonment. The live side-effect potential is implied by the 'Create an order' example, but the 'perform it' wording makes the behavior clear.

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 dense sentences cover purpose, lifecycle, execution rule, return metrics, and usage guidance. There is no filler; the opening contrast with pass/fail e2e orients the agent, and the lifecycle example is front-loaded.

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

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

Even without an output schema, the description enumerates the returned interaction metrics and friction signals, defines the invalidating shortcut, and states the severity of an abandoned journey. Session handling is covered by the schema's detailed session parameter, so an agent has enough to invoke and interpret the 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 the description adds a concrete usage template pairing action:'start' with goal and action:'end' with completed, plus a real example goal. It doesn't add separate semantics for session/note, but those are already well documented in the schema.

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

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

The description states a specific measurement goal — task ease rather than pass/fail — and defines a clear start/end journey lifecycle with concrete signals (backtracks, interaction cost, over-interaction). This clearly distinguishes scout_journey from execution-oriented siblings like scout_click or scout_navigate.

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

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

It explicitly says when to use it: wrap a user goal with start/end and run it on each module's primary journey. It also emphasizes the correct execution method (clicking through UI, no deep-link shortcuts) and treats abandoned journeys as high-severity. However, it doesn't name alternative tools or state 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 and does well: it discloses that the tool 'touches no browser' and that the caller must pass the briefs to lane agents itself. It also explains the balancing guarantee (no overlap, none left unopened) and the return shape, which is needed since there is no output schema. It doesn't cover failure modes or what happens if lanes exceed available routes.

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 sentences, purpose front-loaded, zero filler. It is dense but every clause adds routing or behavioral information. Slightly long, and the return-value clause could be trimmed, 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?

For a 6-param tool with no annotations and no output schema, the description supplies the missing pieces: what it returns, that it has no browser side effects, and the ordering constraint relative to the crawl. Remaining gaps are minor — no explicit mention of what a refused brief looks like or how to handle lane counts exceeding route counts.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by explaining the splitting algorithm ('whole modules per lane, balanced by route count'), which tells the agent how the `lanes` and `routes` inputs actually partition work rather than merely restating their types.

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

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

States a specific verb and resource — it divides an app's known routes across N parallel lanes and returns each lane's session name, objective, and owned routes. The scope ('whole modules per lane, balanced by route count, no two lanes audit the same area') is precise enough to separate it from scout_crawl or scout_lane_report 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?

Explicit timing: 'Call it after the first crawl, when route knowledge is complete.' It also routes the agent forward, naming scout_lane_report as the counterpart for what lanes hand back. It stops short of stating when not to use it (e.g. a single-agent run with no parallel split).

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 behavioral disclosure. It adds a helpful trait ('Touches no browser') and explains the two output behaviors, including the failure case ('reason it was refused'). However, it does not explicitly state whether it has any state-changing side effects or mention permissions/rate limits, leaving some ambiguity for a tool with no annotations.

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

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

The description is information-dense and well-structured: it opens with the run context, then branches into the two modes with concrete outcomes, and closes with a safety note. Every sentence earns its place, though the density requires careful reading. It is slightly long 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?

There is no output schema, so the description must explain return values, and it does: it details the paragraph content for the no-reply mode and the one-line fold or refusal reason for the reply mode. It also explains the input contract for the lane. Missing are details like pagination or error semantics, but for a tool of this complexity it is reasonably 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 100%, so the baseline is 3. The description adds value beyond the schema by explicitly linking the two parameters: omitting `reply` yields the instruction, while providing it triggers parsing. This conditional relationship is not obvious from the schema alone, so the description enhances parameter understanding.

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

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

The description names a specific verb+resource pair: it returns a lane prompt paragraph when `reply` is omitted and parses a lane's reply when `reply` is provided. The opening context 'For a run split across parallel agents (lanes)' clearly frames this as a lane-specific tool, distinguishing it from sibling tools like scout_report or scout_lane_brief.

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

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

The description gives explicit usage conditions: use it when a run is split across lanes, and it precisely states the two modes based on whether `reply` is omitted or provided. It does not name alternatives or exclusions, but the context is clear enough that an agent can decide when to invoke this tool over siblings.

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

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

No annotations are provided, so the description carries the full burden and does: window is visible and closes itself, credentials must never be typed by the agent, a round trip through SSO is followed, closing the window saves nothing, the call returns after waitSeconds with the window still open and must be re-called to keep waiting, and a display is required. This is unusually rich disclosure of side effects, failure modes, and interaction contract.

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?

Purpose and trigger are front-loaded, and every sentence carries operational content (user-facing message text, save semantics, retry loop, headless fallback). It is long for a tool description, but the length is justified by the complexity; only slight trimming would be possible.

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 still covers return conditions, timeout behavior, save semantics, prerequisites (desktop/display), and the fallback procedure. Nothing an agent needs to invoke this correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the waitSeconds re-invocation loop (call scout_login again with the same role), the persistence semantics of role, and the projectPath default behavior. It adds real meaning rather than restating the schema.

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

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

States a specific verb and resource (open a visible browser window for the user to sign in) plus the exact downstream artifact it produces (a saved sign-in for scout_attach { role }). An agent can distinguish this from scout_attach, scout_run_plan, and every other scout_* tool without opening a 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 trigger ('Use it when an attach is refused because no sign-in is saved for the role, or the saved one has expired'), names the related tool scout_attach, and provides an alternative path for headless machines (ask the user to run `scenescout login <url> --role <name>`).

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

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

With no annotations, the description carries the full burden. It does disclose one genuinely non-obvious behavioral trait: a path resolves from the origin's root regardless of which page the session attached on. Beyond that it says nothing about whether navigation waits for load, how failures/redirects are surfaced, or whether the session/target stays attached — significant gaps for a tool whose whole job is a state-changing page transition.

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

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

Three short sentences, front-loaded with the primary target semantics before the path-resolution nuance. The trailing sentence about scout_back earns its place by routing the agent, though it reads slightly oddly as a feature of this tool rather than a redirect.

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 annotations and no output schema, so the description must cover the behavioral profile — it covers target/path resolution but omits load-waiting behavior, failure modes, and what the caller receives back. The remaining four parameters are fully documented in the schema, so the gap is behavioral rather than parametric.

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 does add meaning for `target` by clarifying that a path is resolved relative to the origin root rather than the current page — more than the schema's terse 'Absolute URL or path like /settings' — but it says nothing about `task`, `leave`, or `session`, relying entirely on 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 ('Navigate to') and resource ('a path on the attached origin or a full URL on it'), with a concrete example ('/orders'). It also routes the agent away from this tool for back-navigation ('Also supports \'back\' via scout_back'), which gives partial sibling differentiation, though it does not distinguish itself from scout_click/scout_attach in the same way.

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 agent can infer this is the tool for moving to a new page, and the description explicitly names scout_back as the alternative for back-navigation. However, there is no guidance on when to navigate vs. when the session is already on the target, nor any mention of prerequisites such as needing an attached session.

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

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

With no annotations, the description carries the full burden and does so: read-only, sends nothing, credentials in query strings redacted, list resets on full page load, and scout_request's own calls are marked. It also discloses ordering and the route-change annotation of entries — unusually complete behavioral context.

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

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

Front-loaded with what is listed and the ordering, then usage and safety notes. Dense but every sentence carries information; slightly long for a single paragraph, but 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, yet the description covers return content, ordering, the reset lifecycle, redaction, and integration with scout_request. An agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so all three parameters (limit, session, contains) are already documented in the schema, including the concurrency semantics of `session`. The description adds no parameter-specific detail, so the 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 precise verb and resource ('List the data requests (fetch and XHR) the current page made since its document loaded') and enumerates the returned fields (method, path, status, time, ordering). It is clearly distinguishable from siblings like scout_request and scout_navigate.

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 concrete trigger conditions ('when the page and the server seem to disagree — an empty list where the API has data, a stale value after a save') and the diagnostic goal. It does not name an explicit alternative tool to use instead or state exclusion cases, so it stops short of a 5.

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

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

With zero annotations, the description carries the full burden and discloses the cumulative/persistent nature ('every run starts smarter than the last'), the file location, and the side effects of adds: 'Notes are dated, attributed to the acting role, and deduplicated.' It stops short of exhaustive because edge cases like first-run behavior when ASSUMPTIONS.md does not yet exist, and the exact shape of the read response, are left implicit.

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?

Every sentence earns its place and the purpose is front-loaded, but the whole description is one dense paragraph with a ~70-word parenthetical section list and a dangling clause about engine read-back at the end. The length is proportionate to the tool's conceptual richness (7 sections, 2 actions, content policy), but the lack of structural breaks makes it harder for an agent 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?

Given no annotations and no output schema, the description alone must cover purpose, storage location, usage timing, section semantics, content policy, and behavioral traits — and it covers all of these with concrete examples. Nothing an agent needs to invoke read/add correctly is missing; the only minor gaps (exact read return shape, first-run file creation) are self-evident for this kind of 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%, so baseline is 3; the description adds real value by giving a concrete example for every section enum — e.g., roles: 'qa-role = reviewer: approves orders, cannot administer' and constraints: 'an order can only ship once approved.' It also reinforces note-format guidance and session concurrency semantics, meaningfully elevating what the schema states.

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 opening sentence states the resource and function precisely: 'Cumulative WRITTEN knowledge about the tested app — .scenescout/ASSUMPTIONS.md.' It further disambiguates from coverage tracking with 'memory.json stores coverage; this stores UNDERSTANDING,' and the twin actions read/add are made explicit. An agent can distinguish this from scout_coverage or scout_finding 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 direct operational directives: 'READ it at the start of every session' and 'ADD durable learnings as you go,' plus an explicit when-not rule: 'Do NOT record session-specific facts (ids, counts) — only durable knowledge.' It also names the storage-state trigger ('reads back to you the next time a storage state has expired') and explains the alternative store for coverage, so an agent knows exactly when this tool is the right one.

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, and it states 'Takes no input and touches no browser,' making the read-only, side-effect-free nature clear. It also warns that calling it again is unnecessary and that it duplicates the skill text.

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 tightly packed sentences: content, usage timing/alternative, and input/side-effect constraints. No filler, and the most decision-relevant information appears first.

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 no-input, no-output-schema tool, the description fully covers what the tool returns, when to invoke it, how it relates to the skill alternative, and that it has no browser side effects. Nothing an agent needs to call or follow it is missing.

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

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

The tool has zero parameters, so the schema already says nothing is needed. The description adds the explicit confirmation 'Takes no input,' which aligns with the empty schema, earning the zero-parameter baseline.

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

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

The description uses a specific verb and resource: 'Return the SceneScout testing method' and enumerates its contents (setup order, write modes, exploration, done criteria, reporting). This clearly distinguishes it from the sibling execution tools like scout_attach and scout_report.

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 says when to call it: 'ONCE before the first scout_attach in a conversation, then follow it.' It also names an alternative and provides a rule: if a SceneScout skill is offered, load that instead and 'never read both.'

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

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

With no annotations provided, the description carries the full burden. It states the core behavior and even hints at consequences (modal dismissal, keyboard navigation), but it does not disclose details such as whether the press targets the active page, whether it dispatches keydown/keyup, or how unsupported keys are handled. This is acceptable for a simple action but not richly transparent.

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

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

The description is a single front-loaded sentence with no filler. It immediately states the action, gives examples, and then explains when it is useful — every word earns its place.

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

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

For a simple key-press tool with a well-described parameter schema, the description is largely sufficient. It covers what the tool does and typical use cases. The only gap is an explicit relationship to sibling tools like scout_type, but this is minor given the overall clarity.

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 75%, and the tool description adds essential meaning to the undocumented `key` parameter by providing valid examples. The other parameters already have detailed schema descriptions, so the description's contribution is focused and useful for the one parameter that needs it.

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

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

The description clearly states the action: 'Press a keyboard key' with concrete examples (Escape, Tab, Enter) and signals the intended resource (keyboard). It differentiates the tool from close/click/type siblings by focusing on key-based interaction rather than mouse or text entry, making intent 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 gives clear use cases: 'closing modals and testing keyboard navigation.' It does not explicitly mention when to avoid this tool or name alternatives like scout_type, but the context is clear enough for an agent to choose it appropriately for key-press actions.

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 so well: it names the write target (.scenescout/report.md), explains that the return is a deliberately bounded SUMMARY because full reports exceed client token limits, and discloses the refusal semantics of 'extensive' as an intentional completeness guarantee rather than an error.

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 artifact and its contents are front-loaded before the gating rules, so the key information arrives early. It is dense and long, and the level-gating sentence packs three contracts into one clause, but almost every sentence carries non-redundant 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?

No output schema exists, and the description compensates by explaining exactly what comes back (a bounded summary, not the full document) and where the full artifact lands. For a 5-parameter tool with gating behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics on top: it explains that level must match the contract the run was asked for, that force is a budget-cap escape hatch, and that session enables concurrency across multiple dispatches. The report/history enums are largely restated from 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 and artifact (generate the final markdown report) and enumerates the exact contents (findings, page quality scores, role capability matrix, oracle rollup, gap ledger), which cleanly separates it from siblings like scout_coverage, scout_lane_report, or scout_status that produce different outputs.

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 explicit gating conditions per level and states when force=true is legitimate ('only when the user capped the budget'), which is a genuine when-not constraint. It does not, however, point at any sibling alternative for the partial-report use cases, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden and does so: the fetch runs in-page, carries session cookies, replays the Authorization header, and passes through write-policy interception — with the key caveat that a safe-write refusal here is the engine's safety net, not a finding. It also discloses the return shape (status line, timing, differentiating headers, body truncated at 2000 chars) and that every request lands in the run trail.

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

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

Front-loaded with the core purpose and every sentence carries behavioral information (safety-net semantics, trail recording, origin fencing), but the run-on clause stacking makes it heavier than it needs to be. Information-dense rather than padded.

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

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

With 10 parameters, no annotations and no output schema, the description compensates by describing the return payload, truncation/windowing mechanics, and the write-policy interaction. An agent has enough to invoke it correctly and interpret 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?

Schema description coverage is 100%, so the schema already documents path, method, body, select, offset, limit, headers and session. The description restates body truncation and select/offset behavior but adds little syntax or format meaning beyond what the schema provides, so the 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 precise verb+resource ('Call the app's own API as this session, with the UI bypassed') and immediately frames the scope against the obvious sibling behavior (clicking a control), so an agent can distinguish it from scout_click/scout_network 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?

Explicitly says when to reach for it ('the check that turns a hidden or disabled control into a proven refusal. A button that is not shown proves nothing; the same action refused by the server does') and when not to ('use another session to reach another host'), plus a contrast with a shell call. Selection criteria are unambiguous.

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 meets it by disclosing behavioral consequences: resolved findings move to the green Resolved section and reopen automatically as REGRESSIONS if re-found later. This adds meaningful context beyond the schema, though it does not address potential side effects like irreversibility or permissions.

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 concise sentences with no filler. It front-loads the core action, then explains behavior and usage conditions. Every sentence contributes useful information.

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

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

The description covers purpose, usage triggers, and behavioral outcomes, which is sufficient for a simple action tool with no output schema and no required parameters. It does not explicitly explain the return value, but given the tool's simplicity and the strong schema coverage, the remaining gap 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 description coverage is 100%, so the parameters are already well-documented. The description adds minor value by hinting where to find the id ('shown when recorded and in the report'), but it does not elaborate on parameter formats beyond the schema, hence a baseline score.

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-resource pair ('Mark a finding as resolved') and clearly identifies the target (by id). It distinguishes itself from sibling tools by explaining the outcome (moving to the Resolved section and auto-reopening as REGRESSIONS), which is unique to this tool.

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

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

The description explicitly states when to use it: when the user says a bug is fixed, or when re-testing shows the evidence no longer reproduces. It does not provide when-not-to-use guidance or name alternatives, but the usage context is clear and actionable.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses abort-on-first-new-violation semantics, that repeated violations do not abort, policy-refusal and failed-step stops, the returned transcript, and the exact continue-mode behavior. It also specifies execution-time target resolution and select-step failure, which an agent could not infer otherwise.

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

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

Front-loaded with the core purpose and batching rationale, and each sentence conveys a distinct behavioral rule. It is dense and long, but the length is largely justified by the failure-mode detail; only minor tightening is possible.

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 complex batched-action tool with no annotations and no output schema, the description covers abort conditions, per-step failure, continue-mode behavior, and the returned transcript. Return-value detail beyond 'a transcript of how far it got' is thin, but overall it is complete enough to invoke 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 coverage is already 80%, but the description adds real meaning: targets resolve at execution time by semantic locator and 'never snapshot refs', plus the upload value being a fixture kind or project-relative path. Most other param detail (onViolation, task) mirrors the schema, so it earns above the baseline 3 without being exhaustive.

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 scope ('Execute up to 20 actions in ONE call') and immediately names the intended scenarios ('fill a form, walk a wizard'), which clearly separates it from the single-action siblings like scout_click and scout_type. An agent can tell what this does and when it beats multiple round-trips 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 clear when-to-use context: mechanical sequences vs a 'sweep of independent steps' with onViolation 'continue'. It explains the stop-vs-continue decision well, but never explicitly names a sibling alternative (e.g. 'for a single action use scout_click'), so the routing 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It conveys a read-only reconnaissance behavior by saying 'scan a project directory to discover...' but does not mention whether state is persisted, what the return shape looks like, or if any environmental prerequisites exist. This leaves some behavioral ambiguity.

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 plus the useful sequencing directive 'Run this first.' It frontloads the action and follows with a concrete list of discovery targets, containing no filler or redundant repetition of the tool 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 one-parameter tool with no annotations and no output schema, the description provides the essential call context: what to pass, what will be discovered, and that it should be invoked first. It does not explicitly describe the return format, but the enumerated discovery targets partially compensate and make the tool callable.

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

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

The only parameter, projectPath, is already fully documented in the schema as 'Absolute path to the project root,' and the description adds no additional constraints, defaults, or format details. The discovered artifacts listed in the description concern tool output rather than parameter semantics, so the schema remains the primary source of parameter meaning.

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 ('scan') and object ('project directory') and enumerates the concrete artifacts it uncovers: frontend workspace, framework, routes, dev command, Playwright auth storage states, and testid conventions. This makes its role as a project discovery tool unmistakable and distinguishes it from execution-oriented siblings. The directive 'Run this first' also makes its purpose immediately clear.

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

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

The description explicitly instructs the agent to run this tool first, establishing clear sequencing relative to the many scout_* sibling tools. It does not name specific alternatives or conditions for choosing another tool, but the 'first' directive gives the agent enough contextual guidance for initial invocation.

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 burden, and it does well by disclosing the JPEG format, viewport scope, and the 'LAST RESORT' nature of the tool. It could be slightly more explicit about side effects or what the caller receives, but the core behavior is transparent.

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 one dense, front-loaded sentence with no filler. It packs the main action first and the routing caveats after, though the long em-dash chain is slightly less scannable than a short two-sentence structure would be.

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

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

The description is complete enough for selecting and invoking the tool: it says what is captured, in what format, and when not to use it. With no output schema, it slightly underspecifies the result format or delivery mechanism, but that is a minor gap for a simple screenshot tool.

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

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

Schema description coverage is 100%, so the sole optional `session` parameter is fully documented in the schema. The description adds no parameter-specific detail, but none is required beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Take a JPEG screenshot of the current viewport.' It also clearly distinguishes itself from siblings by naming what belongs in scout_snapshot and scout_design_audit instead.

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?

This is exemplary routing guidance. It tells the agent to use this tool only for pixel-native content that computed data cannot capture, and explicitly directs geometry issues to scout_snapshot, style/contrast/spacing issues to scout_design_audit, and broken-image checks to the BROKEN IMAGES section of scout_snapshot.

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 behavioral burden, and it is unusually rich: it discloses the fallback to the largest scrollable pane on app-shell layouts, that smaller regions beside it never move, that it reports SCROLL LOCKED, and that scrolling triggers lazy-loaded content. This goes well beyond what the schema alone reveals.

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 long and dense, but nearly every clause carries behavioral or workflow value, and it is front-loaded with the core action. Some rhetorical framing ('real apps hide their bugs below the fold') could be trimmed, and the parenthetical caveats make it a wall of text rather than a scannable definition, but it is efficient for the complexity it documents.

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 4 optional parameters, no output schema, and no annotations, the description covers the essential missing context: result format (px and %), SCROLL LOCKED detection, fallback behavior, target-region semantics, and why scrolling matters for audits and lazy-loaded content. The schema handles the remaining parameter details, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value on top by explaining the target semantics in depth — single region, nearest scrollable ancestor, and the 'smaller region beside it' trap. It does not redundantly restate by/to/session, leaving the schema to cover those.

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 behavior ('Scroll like a user'), the resource acted on (page or one target region), and the outcome (reports position in px and %, flags SCROLL LOCKED when scroll is blocked). It clearly differentiates itself from sibling tools like scout_snapshot and scout_design_audit by being the scroll-position-changing action that precedes 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?

It gives explicit workflow guidance: use before judging a long page, then re-snapshot/re-audit deep sections, because the design audit measures at the current scroll position. It also warns against calling a nav item missing without scrolling its own container first, which is a concrete when-to-use versus when-to-target instruction.

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 ordered matching algorithm (exact value, exact label, case-insensitive, prefix) and the failure mode (ambiguous or unmatched values are refused immediately with the option list). It omits success behavior and whether it dispatches change events or waits for options to populate.

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

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

Three sentences, front-loaded with the action and then the resolution rules, with no filler. The middle sentence is dense but each clause carries distinct information about matching order.

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 no-output-schema, no-annotation tool the description covers the critical decision logic and error behavior an agent needs to call it correctly. Minor gaps remain around success signaling and whether the element must be visible, but nothing essential is missing.

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

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

Schema coverage is 80%, so baseline is 3, and the description genuinely adds meaning for `value` by spelling out the match precedence and the ambiguity/prefix behavior that the schema's one-line note only hints at. The ref/task/session/objective params get no added explanation, but they are covered by 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 and resource ('Select an option in a <select> by ref'), which is inherently distinct from scout_click/scout_type because it targets a native select and uses option matching rather than coordinates or text entry. It never names a sibling to contrast against, so it stops 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?

Usage is implied by the matching rules (you reach for this when you have an option value or label), but the description never states when to prefer it over scout_click on an option, nor any preconditions such as the select needing to be present/visible. No explicit when/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 supplied, the description carries full behavioral burden and meets it: it discloses default-session persistence, that switching default does not deauthenticate other sessions ('Both browsers stay live and authenticated'), and the effect of paceMs on live sessions. It also hints at re-snapshotting after a break, adding operational behavior beyond the schema.

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

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

Three dense sentences, front-loaded with the core action, then usage guidance, then behavioral caveats. Every sentence earns its place and no tautology or 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?

For a 3-optional-parameter tool with no output schema, this is nearly complete: purpose, default behavior, persistence, and speed control are covered. It does not describe the shape of the listing result or edge cases like unknown session names, but the stated behavior is enough for an agent to decide confidently.

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

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

Schema coverage is 100% so the schema already documents each parameter. The description still adds value by explaining that the default is what is used when a tool call omits session, and by contrasting direct session passing with default-based convenience. Minor: it could restate paceMs semantics, but schema already covers them.

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?

Description opens with a precise dual function: 'List live sessions, or set which one is the DEFAULT' and explains what DEFAULT means. This distinguishes scout_session from sibling action tools like scout_snapshot or scout_navigate while making its resource ('sessions') explicit.

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

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

Gives explicit decision guidance: prefer passing session on each call for multi-role/concurrent work, and use scout_session for sequential convenience or checking what's live. It names the context that should steer an agent away from this tool, which is exactly what a usage guideline should do.

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 does so richly: it discloses the diff semantics (re-snapshot returns a DIFF even after visiting elsewhere, per-tab diffing), ref stability across query-string rewrites, truncation behavior past the element cap, and relative cost. These are non-obvious behaviors an agent could not infer from the name or 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?

Front-loaded with the core purpose, and every clause carries information (return fields, diff behavior, ref stability, cost). It is dense and somewhat run-on in the middle, which slightly hurts scannability, but there is little wasted text.

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

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

There is no output schema, so the description must describe the return payload — and it does, itemizing exactly what a snapshot contains (refs, states, announcements, geometry, coverage, oracle violations) plus diff/truncation behavior. An agent has everything needed to call and interpret 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%, so both `full` and `session` are already documented in the schema, including the concurrency caveat. The description adds no format/semantic detail beyond that, so the baseline of 3 is correct 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?

Specific verb ("Capture") plus a fully enumerated resource: URL, fingerprint, summary, interactable elements with refs, announcements, geometry, coverage, oracle violations. It explicitly positions itself against a sibling ("prefer this over screenshots"), so an agent can distinguish it from scout_screenshot/scout_capture without opening a 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?

Clear usage context: it names the alternative (screenshots) and states the cost tradeoff, and it explains the multi-session concurrency case for the `session` param. It lacks explicit when-not guidance against the many other scout_* capture/verify siblings, but the routing signal is strong.

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 states it takes no input, touches no browser, and discloses host-dependent rendering (MCP Apps pane vs. plain text) plus the instruction to pass on the 'Live view:' address. It stops short of explicitly declaring the operation read-only/idempotent, which would fully close the 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?

Three sentences, front-loaded with what the output contains before moving to when to call it and how it behaves across hosts. Every sentence carries information, though the phrasing ('the person running you how the run stands') is slightly indirect for a zero-param 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 supply the return shape itself, and it does: sessions, objectives, tasks, findings by severity, coverage, and the live-view address. An agent has everything it needs to call this correctly and describe 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?

Zero parameters, so the baseline is 4. The description reinforces this with 'Takes no input,' which matches the empty schema and prevents an agent from inventing 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?

The description names a concrete resource (the run's status) and enumerates exactly what it reports: per-session objective and current task, open findings by severity, coverage, and the live-view address. It implicitly separates itself from the browser-action siblings via 'touches no browser,' but never distinguishes itself from close cousins like scout_status_poll, scout_coverage, or scout_report.

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

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

It gives an explicit trigger: 'Call it when the user wants to watch or asks how the run is going.' That is clear usage context, but there is no when-not guidance and no named alternative for the overlapping status/coverage/report 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 present, the description carries the full burden, and it does disclose real behavioral traits: the invocation cadence (every few seconds) and the intended consumer (a UI pane, not the agent). It stops short of describing the return payload or whether polling is cheap/idempotent, but the caller constraint is the behavior that matters most here.

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, and the audience constraint is front-loaded immediately after the mechanism. Nothing is padded 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?

For a zero-parameter, output-schema-less UI polling endpoint, the description supplies the one thing an agent needs: do not call this, call scout_status. Return-shape details are absent but legitimately irrelevant to the agent audience the description has already excluded.

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 already fully covers its surface and there is nothing for the description to disambiguate. Baseline for a parameterless 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 names the specific caller (the scout_status pane) and the specific action (refreshing run status), so the resource and operation are identifiable. It is also clearly distinguishable from the sibling scout_status, though it never spells out what payload the poll actually returns.

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

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

It gives an explicit negative use case ('Not for the agent') plus a named alternative ('call scout_status instead'). An agent has everything it needs to route away from this tool with no inference required.

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 lists the recognized formats (Given/When/Then, checklists, numbered, "AC1:", "Acceptance criteria" heading), notes multiple tickets may be given, states unrecognized tickets are reported rather than guessed, and discloses "Touches no browser." It omits auth/rate-limit details, but for a local parsing tool that is minor.

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

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

It is a dense single paragraph that is front-loaded with the core action (read and retain criteria) before the parsing details. Slightly long, but every clause conveys a distinct behavior rather than 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?

There is no output schema, yet the description explains what is returned (criterion ids AC1, AC2, …) and the not-recognized case, so an agent knows what to expect. Combined with the named downstream tool, this is essentially complete for a parsing/ingest tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, giving a baseline of 3. The description restates that criteria come from `text` or `path` but adds no format or size detail 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?

Specific verb+resource: it reads tickets/acceptance criteria from `text` or `path` and stores them for the report. It clearly distinguishes itself from siblings by naming scout_criterion as the downstream tool used to judge each returned id, so an agent can place it in the workflow without opening a 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 the context clearly ("the tickets or acceptance criteria the person gave this run") and routes the follow-up to scout_criterion. It does not, however, state when NOT to use it or contrast it against nearby capture tools like scout_playbook/scout_note, leaving that 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 disclosure burden and exceeds it. It details append semantics, the separating-space rule, empty-text clearing, replace behavior, the exact event side effects (input fires, keydown does not), and the fact that the result reports pre-existing content. This is exemplary behavioral documentation.

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 dense but every clause earns its place: purpose, append behavior, replace semantics, clearing rule, event caveat, and usage scope. It is front-loaded with the core action and then systematically covers edge cases. Length is justified by the behavioral complexity.

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

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

For a tool with no annotations and no output schema, the description covers the full operational surface: how content is entered, when it is cleared, what side effects occur, and what the result reports. Nothing an agent needs to invoke it correctly or anticipate its behavior is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the interaction between textValue, replace, and empty-string clearing, and by clarifying which event behaviors apply. It enriches the parameters without restating their schema descriptions.

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

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

The description names a specific verb ('Type') and resource ('text input/textarea/composer by ref'), and immediately distinguishes the tool's core behavior — appending vs. replacing — which separates it from sibling input tools like scout_click or scout_press. The purpose is unambiguous and action-oriented.

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 states a broad use case ('valid values and boundary/fuzz values') and gives a critical constraint (keydown-driven triggers won't react to appended text), which effectively tells the agent when behavior may not match expectations. It does not name a sibling alternative (e.g., 'use scout_press for keydown-sensitive actions'), but the guidance is sufficiently clear for 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 full behavioral burden and succeeds remarkably. It discloses the chooser interception, in-memory fixture generation, project-fencing of `filePath`, accept-violation flagging, warning if the input is cleared, and detection of state-changing requests. This goes far beyond a simple 'uploads a file' summary.

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 long but dense with operationally relevant detail; nearly every clause adds value. It is front-loaded with the core purpose and then proceeds from ref targeting to fixture/file selection to post-selection behavior. A few parentheticals could be trimmed, but the length is justified by the tool's complexity.

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

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

Given the tool's complexity, zero annotations, and no output schema, the description is remarkably complete. It covers the input-targeting strategy, file source options, validation behavior, state-change detection, and necessary follow-up actions. An agent has enough context to invoke the tool correctly and interpret its result without additional structured metadata.

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 description adds substantial meaning beyond the schema: `ref` resolution through styled controls, fixture kind inference from the accept attribute, project-fencing semantics for `filePath`, and `name` use for boundary tests. It also explains the result fields tied to these parameters, making parameter behavior concrete.

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

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

The description opens with a specific verb and resource: 'Attach a file to an upload control the way a user does.' It clearly distinguishes the tool's scope from general file operations by detailing `ref` targeting of file inputs, hidden inputs, and chooser-opening controls. The distinctive behavior of intercepting the chooser makes it unambiguous among sibling tools.

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

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

The description gives extensive usage context: when to omit `ref`, how to distinguish fixture-based uploads from `filePath` uploads, and what to do after a selection that fires no state-changing request. It does not explicitly name alternative sibling tools or state when not to use this tool, but the parameter-level guidance is clear enough for correct invocation.

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 it delivers: it discloses ordering (worst route first), grouping, returned content (evidence and repro steps), and the state effects of each verdict—'gone' resolves, 'present' confirms, 'changed' keeps open. This is unusually transparent about 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?

Every sentence earns its place: the tool's action, the worklist behavior, narrowing, verdict recording, and usage timing. The information is front-loaded with the core purpose and flows logically without repetition or fluff.

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

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

For a tool with five parameters, no annotations, and no output schema, the description is remarkably complete. It covers what the worklist returns, how to narrow it, how to record verdicts, and what each verdict means, leaving no critical gap for an agent trying to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the interaction between id, ids, and verdict—including that a verdict is recorded by calling again with id and verdict—and clarifies what the verdict values do to report state.

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

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

The description clearly states the tool's purpose: re-test findings left open by previous runs and record verdicts. It distinguishes itself from siblings like scout_scan or scout_resolve by describing a specific verification workflow with 'gone', 'present', and 'changed' outcomes.

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 explicit when-to-use context: 'Use after a fix wave, or at the start of a run against an app this project has tested before.' It also explains the call pattern for listing, narrowing, and recording verdicts. It does not mention alternatives or when-not-to-use, so it stops short of a 5.

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