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

With no annotations, the description carries the full burden and does: it discloses that write policy is enforced at the NETWORK layer with per-method rules, that 'destructive' is user-opt-in only, that a missing role login refuses the attach and names the fix, and that multi-session coverage/findings merge into one project memory. That is exactly the enforcement/auth/concurrency context an agent cannot infer.

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 and most content is necessary for a 22-parameter, unannotated tool, but the write-policy sentence is a dense run-on with four clauses chained by dashes and semicolons, and the role/session passage lacks structure. Readable but not scannable.

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 session-establishing tool with 22 params, no annotations and no output schema, it covers the high-stakes surfaces (write policy, auth, plan gating, session concurrency) and failure behavior. Lower-stakes knobs (evidence, record, open, browser) are left entirely to the schema, which is acceptable at 100% coverage, but the description never says what the attach itself returns.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema defers to — the schema's `mode` description literally says "see tool description," and the description supplies the per-mode request rules. It also explains the `role`/`session` relationship (one browser per role, target via each tool's `session`).

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

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

Opens with a concrete verb+resource: "Launch a browser and attach to a running web app." It is clearly distinguishable from sibling action tools (scout_click, scout_navigate) — this is the session-establishing tool — and it names the prerequisite sibling scout_playbook.

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 selection criteria for every mode: observe for targets with real data, safe-write "when the user wants create/edit flows tested", destructive "ONLY when the user explicitly confirmed a disposable/seeded environment", plus a sequencing rule (call scout_playbook first on a first attach). It also names the alternative path (role vs storageStatePath, scout_session for defaults).

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, yet it says nothing about behavior: what happens at the start of history, whether the navigation waits for load, whether a beforeunload prompt can block it (the schema's `leave` param implies it can), or what the result indicates.

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

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

A single short sentence with no waste; the core action is front-loaded. It is arguably too terse for a tool with zero annotations, but nothing is redundant.

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

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

The tool is simple and its schema is richly documented, so most calling information is present. However, with no annotations and no output schema, the description leaves behavioral expectations (history boundaries, prompt handling, result reporting) entirely unaddressed.

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

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

Schema description coverage is 100% and the parameters (task, leave, session, objective) are thoroughly documented in-schema, including the beforeunload semantics. The description adds nothing beyond baseline for parameters.

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

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

States a specific verb+resource ("Go back in browser history") and adds the testing intent in parentheses. It is clearly distinguishable from scout_navigate and scout_click, though it doesn't name those siblings explicitly.

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

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

The parenthetical "tests back-button resilience" hints at when this is used (back-button/beforeunload resilience checks), but there is no explicit when-to-use vs. scout_navigate, no exclusion conditions, and no mention of what to do if there is no history.

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?

Without annotations, the description carries the full burden. It discloses that it saves a file under a specific path and uses a real screenshot, which is useful, but it does not describe what the return value is, whether files are overwritten, or any permission/error behavior expected for a write 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?

Three short sentences, front-loaded with the core action and output location. The prerequisite and exclusion follow logically with no wasted words.

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

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

For a write tool with no annotations and no output schema, the description covers purpose, prerequisite, and one alternative adequately. However, it omits behavioral details an agent might need—such as the format of the return value or file collision behavior—leaving it minimally sufficient rather than 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 schema already documents each parameter thoroughly. The description adds a note about using a ref from the latest scout_snapshot, but that is already present in the schema's ref description, so it adds little semantic value beyond the structured fields.

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 (Save), resource (PNG of ONE element), scope (bounds plus margin), output location (.scenescout/captures/), and purpose (to show a person how it looks). It also explicitly distinguishes itself from the design-audit sibling, so an agent can tell what this tool uniquely does.

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

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

Provides clear context: it requires a ref from the latest scout_snapshot and explicitly says it is not for judging design (use scout_design_audit instead). It does not mention the full-page screenshot sibling, but the 'ONE element' emphasis gives adequate guidance for most calls.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds non-obvious behavior: defaults exclude fixed and 'not-a-bug' findings, the not-a-bug count is still surfaced, and an explicit escape hatch (`filter {feedback: ["not-a-bug"]}`) is given. It also discloses inline picture caps (10 images, 1024 px) and that it 'touches no browser', none of which appear in structured fields.

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 ordering, then usage, then defaults, then pictures — a sensible priority order with zero filler sentences. It is one long run-on paragraph with stacked parentheticals, which makes it denser than it needs to be and slightly harder to scan than a bulleted or multi-sentence structure.

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

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

For a read-only listing tool with a full output schema, every agent-facing question is answered: what is returned, in what order, what is hidden by default, how to reveal it, how pictures are delivered, and that no browser interaction occurs. Nothing needed to invoke it correctly 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 a 3 is the floor, and the description goes beyond it: it explains the default exclusion of fixed/not-a-bug and how to override it, that `ids` bypasses status/label filtering, and that 'files' is the default picture mode with inline limited to 10 images at 1024 px. The `limit` parameter is not mentioned in the description, a minor gap given the schema covers it.

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

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

States a specific verb and resource ('Show the project's findings as plain cards') plus the ordering rule ('worst first') and enumerates exactly what each card contains (impact, title, problem kind, page, steps, expected, actual, id). That level of specificity makes it unmistakable against siblings like scout_report or scout_recap, which imply aggregate/reporting output rather than per-finding plain-text cards.

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 trigger conditions: 'at the end of a guided check, or whenever the person wants to read what was found in plain words,' and adds an output-format instruction ('post each card's text as it is'). It does not name a sibling alternative or say when to prefer scout_recap/scout_report instead, which keeps it 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 no annotations, the description carries the full behavioral burden. It usefully discloses that the tool returns the outcome plus oracle violations and that the result says whether duplicate submissions fired, but it does not state broader safety details such as whether clicks can navigate away, require auth, or cause irreversible state changes.

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 front-loaded with the core action and return behavior, then explains the multi-click probe. The second sentence is dense but purposeful, and 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?

For a parameter-rich interaction tool with no annotations and no output schema, the description covers purpose, click semantics, and return highlights. However, it leaves out important behavioral context around side effects, navigation, and destructive risk, which is a noticeable gap for a click 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 six parameters. The description still adds meaningful semantics for clicks by explaining the IMPATIENT-USER double-submit probe and what a positive result means, and it clarifies that ref comes from the latest scout_snapshot.

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

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

The description states a specific action and resource: clicking an element by its ref from the latest scout_snapshot. It also distinguishes the tool's outcome focus by noting it returns the result plus oracle violations, which helps an agent understand this is an interaction-and-check tool rather than a generic browser action.

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 for the multi-click probe, including when to use clicks=2 or 3 and that it should be used once on important submit/create buttons. It does not explicitly compare against siblings such as scout_press or scout_select, but the core when-to-use guidance is present.

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

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

With no annotations, the description carries the full burden and does well: it discloses that memory persists on disk, that the default target is the default session, that lane sessions are held open until their report is accepted, and that refusals enumerate blocked lanes. It omits the destructive consequence of `force` (though the schema covers it), which is the main behavioral gap.

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

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

The description is front-loaded with the core action, then proceeds through the default, the explicit parameters, and the lane constraint. Every sentence earns its place, including the longer lane caveat that prevents a real misuse.

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

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

For a 3-parameter close tool with no output schema, the description covers purpose, default behavior, bulk closing, and the critical lane-report dependency. It is largely complete, though it could mention `force` and what happens to a session after closure (e.g., whether it can be reopened) to be fully self-contained.

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 thoroughly, including the risky `force` behavior. The description largely restates the default and `all` semantics and adds only modest context (end-of-multi-role-run usage), so it does not add much beyond the structured 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 verb and resource: 'Close a session's browser', with the important qualifier that memory persists on disk. It is immediately clear what the tool does, though it does not explicitly contrast itself with sibling tools such as scout_session that likely create or switch sessions.

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 routing: default closes the default session, `session` targets a specific one, and `all=true` is for the end of a multi-role run. It also states a when-not condition for lanes pending report folding, but never mentions the `force` escape hatch, so the agent reading only the description lacks the full set of options.

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

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

With no annotations, the description carries the burden and does disclose the non-obvious default: session-scoped in a parallel run but project-wide when no other session shares the project, plus that project scope tags each form and route with the sessions that saw it. It omits any permission, cost, or pagination behavior, so it is strong but not complete.

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 content list are front-loaded in the first sentence, with the scoping behavior after. The second sentence is dense and partly restates the scope enumeration already in the schema, but every clause carries information.

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

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

No output schema exists, and the description does describe what is returned (visited states, unexercised elements, tagged routes/forms), which an agent needs to interpret the result. The only gap is that the exact shape of the returned coverage data is not characterized.

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 meaning beyond the schema: it explains why the default flips between session and project, and that 'project' tags forms/routes with the sessions that saw them, which the schema does not 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?

States a specific verb and resource ('Show exploration coverage') and then enumerates the concrete content: states visited, unexercised elements, unselected dropdown options, and unsubmitted blank-field forms. That content distinguishes it from reporting siblings like scout_status or scout_lane_report, though no sibling is named explicitly.

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

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

'Use to decide where to explore next and when the level's budget is satisfied' gives a clear decision context, and the parallel-run sentence explains when session vs project scope applies. No explicit exclusion or named alternative is given, 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 no annotations, the description carries the full burden and does most of it: it discloses the side effect (states recorded into coverage memory), the safety profile ('Navigation-only — safe in read-only mode'), and the default crawl scope (all known routes not yet visited). It does not disclose cost/duration, request volume, or what happens on the 150-path cap, which matters for a tool that sweeps up to 150 routes in one call.

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 lead clause front-loads the identity and the 'ONE call' differentiator, and the closing sentence carries the routing advice. The first sentence is dense with a long parenthetical status glossary, but each item listed is information an agent needs to interpret the return value.

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 the returned per-route signals including the special ERROR-VIEW and STILL-LOADING states. Combined with the stated default scope and safety mode, an agent has enough to call it and interpret results without further discovery.

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 schema already explains path resolution semantics and the concurrent multi-session use of `session`, so the description adds little beyond restating that it visits 'each path'. Baseline 3 applies since structured fields do the heavy lifting.

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

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

States a specific verb and resource ('route sweep... visits each path') plus the exact outputs: coverage memory writes and a per-route health summary enumerating HTTP status, element count, main-area contents, oracle violations, dead-ends and auth-redirects. It also carves out its scope against the interactive tools ('Navigation-only', 'explore interactively only where it flags problems'), so an agent can separate it from scout_click/scout_navigate 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?

'Use this FIRST for broad coverage; explore interactively only where it flags problems or where journeys matter' is an explicit ordering rule with a named condition that selects the alternative. The default behavior when `paths` is omitted is also stated, so the agent knows what happens on a bare call.

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

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

With no annotations, the description carries the full burden and does well: it discloses that re-recording replaces the prior verdict (mutation/idempotency semantics) and that the tool 'touches no browser' (side-effect boundary). It could say more about permissions or what happens across sessions, but the key behavioral traits 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?

The description is front-loaded with the core action and stays dense but purposeful; each sentence (verdict semantics, finding linkage, replacement behavior, no-browser note) earns its place. Slightly long, 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?

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the essentials: what is recorded, how findings link, replacement behavior, and side-effect scope. Nothing critical appears missing for correct invocation, though more on cross-session or concurrency implications could round it out.

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 would be 3. The description adds value beyond the schema by framing the criterion-to-finding link as the agent's judgement stated with confidence rather than word-matching, and by spelling out that a fail names findings while not-tested uses untestedBecause — reinforcing the conditional parameter relationships.

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

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

The description states a specific verb (record) and resource (a verdict on one acceptance criterion of a ticket read via scout_tickets), plus the confidence dimension. It distinguishes itself from siblings by referencing scout_tickets for the source and scout_finding for the linked evidence, so an agent can tell what it does and what it does not.

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

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

It gives explicit conditions: file findings with scout_finding FIRST when the verdict is 'fail', and explain 'not-tested' via untestedBecause. It also states the replacement behavior (re-recording the same criterion from the same session overwrites the earlier verdict), leaving little to inference.

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

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

No annotations, so the description carries the full burden, and it does substantial work: it enumerates what is measured, discloses that keyboard-focus sampling uses 'real Tab presses' (an actual page interaction, not a passive read), and explains the four-page threshold before the SITE CONSISTENCY block appears. It does not state runtime cost, whether the page must be loaded/authenticated first, or that the audit is read-only with respect to the page.

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 one-line purpose before the catalogue of checks. The middle run of check names is long but each item defines an output category the agent will receive, so it earns its space; the tail about four-page site consistency is more than a caller needs up front.

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 convey the return shape — and it does: ⚠ measurable defects, → craft suggestions, SYSTEM SUMMARY, PAGE SCORE with a why: line, and the conditional SITE CONSISTENCY block. An agent knows what it will get back and how to use 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?

One optional parameter with 100% schema coverage, and the schema already explains the concurrency-vs-sequential semantics of `session` in detail. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource: a computed-style design audit of the current page. Explicitly distinguishes itself from the screenshot-based siblings (scout_screenshot, scout_capture) with 'WITHOUT screenshots', so an agent can route between them 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?

'Run once per representative page' gives clear execution context, and the closing sentence tells the agent what to do with the results (file → items as ux-polish findings with concrete numbers). It stops short of naming a specific alternative tool to use when the agent wants visual rather than computed-style evidence.

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

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

Goes well past annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing consequences: the finding is kept either way, retains its id, and later filings of the same problem still merge into it, while not-a-bug entries are surfaced separately in cards and the status pane. It also bounds export mode (candidates only, never alters the answer key or dedup on its own) and states 'Touches no browser.' That is exactly the non-obvious side-effect context an agent needs before mutating.

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?

Primary action is front-loaded in the first clause and almost every sentence carries load-bearing information about side effects or admissibility. The export behaviour is buried mid-paragraph behind semicolons, making the mode harder to spot than it should be, but nothing is padded.

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

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

With annotations and an output schema already present, the description fills the remaining gaps: mutation semantics, persistence of the finding and its id, dedup behaviour, separate surfacing of not-a-bug, export's read-only-for-maintainers scope, and the absence of browser interaction. An agent can call this correctly and predict the result without further information.

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

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

Schema description coverage is 100%, so the schema already documents id, export, reason and verdict, including the 'Required unless export' conditional. The description mainly restates those facts (the 300-character limit, the two verdict strings) and adds little syntax or format detail beyond them; 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?

Names a specific verb and resource ('Record the person's own verdict on a finding') and enumerates the two allowed verdict values, so the action is unambiguous. It does not contrast itself with plausibly overlapping siblings such as scout_finding, scout_resolve or scout_verify, so an agent must infer which one records a human verdict versus which drives automated resolution.

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 admissibility rule — 'Call it only with what the person said; never label a finding yourself' — which is a real when-to/when-not constraint an agent could otherwise get wrong. It also explains the alternate export mode. It stops short of naming a sibling alternative for the case where the agent does want to act on a finding itself.

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

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

With no annotations, the description carries the full burden and does real work: it discloses deduplication across runs, automatic capture of the action trace as repro, automatic element/viewport screenshotting, persistence into report.html, and return of that image. It does not state what happens on a duplicate hit (merged? returned id?) or permission/session prerequisites, which are the remaining behavioral gaps 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?

Effectively one dense paragraph of three sentences, front-loaded with the action and followed by purpose/behavior/examples in a sensible order. It is long but nearly every clause carries information; the parenthetical about report.html and the returned image is slightly buried mid-sentence.

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 write tool with no output schema, the description covers purpose, side effects, storage, and return (image), which is most of what an agent needs. Missing are severity grading guidance and the outcome of deduplication, which matter for correct invocation but are secondary.

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 88%, so baseline is 3 and the description adds little beyond it: ref semantics are restated, and category is only implied through examples. `severity` is required with an enum and no schema description, yet the description never says how to grade high/medium/low — a real omission the description could have filled.

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

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

Opens with a specific verb+resource ('Record a structured finding') and immediately narrows the domain to bugs, UX issues, and improvements, then enumerates concrete qualifying cases (crashes, dead ends, missing testids, ux-polish). It is unmistakably a write-a-defect tool rather than a navigation or inspection tool, though it never names the nearest sibling (scout_note) to draw the line explicitly.

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

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

'Use for anything worth reporting:' followed by a concrete enumeration gives clear positive selection criteria, and the convention field adds a genuine negative case ('Not for "I could not tell": leave that unfiled'). It lacks an explicit contrast with scout_note or scout_ticket_file, so the agent must infer when a finding becomes a ticket.

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

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

Beyond the annotations it discloses that acceptance can only come from the person in the form, that the call has no browser side effects, that failure is reported in the result, and that retrying is forbidden. These are critical behavioral facts the annotations (readOnly=false, openWorld=false) do not convey.

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

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

It is front-loaded with the core action, but the sentences are long, nested, and syntactically tangled (e.g. 'a guided plan whose care level writes may start'), making it harder to scan than necessary. The content earns its place, but the structure costs readability.

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?

Output schema exists, so return values need not be explained, and the description still covers failure modes and the no-browser trait. For a single-parameter human-gated confirmation tool this is nearly complete, with only the form mechanics 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 coverage is 100% and the single planId parameter is fully documented in the schema. The description adds the useful clarification that no parameter value can itself accept the plan, but gives no format or sourcing detail beyond the schema's own note. 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?

The description states a specific action (ask the person, via a server-shown form, to confirm a guided plan) and names the exact conditions the plan must meet. It is clearly a human-in-the-loop confirmation gate, distinct from scout_run_plan or scout_guided_plan. The phrasing is dense enough that the purpose takes some parsing, keeping 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 explicitly says the agent may make the call but cannot answer it, that nothing passed accepts the plan, and that it must never be retried on the person's behalf. It enumerates the decline paths (close, go back, mistype, client cannot show forms) and prescribes the fallback of offering the check in Look only, which is exactly the when/when-not guidance an agent needs.

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

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

Beyond readOnlyHint=true, it discloses the acceptance state machine a plan may land in, why it happens (writing care level on a remote site, or creating test data anywhere), and the concrete consequence on scout_attach. It also confirms the tool touches no browser, which is the key behavioral fact for an agent deciding whether to call it.

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

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

The build/read split is front-loaded and every sentence carries governance information that an agent needs. It is dense, with long compound sentences and several policy clauses stacked together, but nothing is filler.

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

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

The annotations cover the safety profile, the schema covers all parameters, and an output schema exists, so the remaining burden on the description is behavioral and procedural. It covers that fully: build vs read mode, acceptance gating, the confirm handoff, and the maxMode ceiling.

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 enum-level detail (care, areas, signIn, thoroughness) already lives in the schema descriptions, so the schema does the heavy lifting. The description restates the exactly-one-of choices/planId rule, which the schema also says, and adds little new parameter-level semantics. 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?

The description opens with a specific verb and resource: turns guided choices into a plan, and can also read back an existing plan by id. Both entry modes (choices vs planId) are stated explicitly. It does not differentiate itself from similar siblings such as scout_playbook, scout_run_plan, or scout_recheck_plan, so it stops short of a 5.

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

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

It states exactly when to use each mode ('Pass choices to build a new plan, or planId to read one already built'), and notes the panel scenario where only an id is handed over. It also spells out downstream rules: unaccepted plans block scout_attach above observe, scout_guided_confirm asks the person, and a care level above the config's maxMode is refused.

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 load and does well: it discloses the return shape, that results are diffed against pre-hover state, that each item is truncated to 300 chars, and that on busy pages new text may be unrelated and is labelled as such. It does not cover wait/timing behavior for animations or whether the hover is dismissed afterward, which are the remaining material gaps for this kind of 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 action and the payoff (what it reveals), then the caveats about truncation and possibly-unrelated text, then the usage directive. Dense and largely waste-free, though the second clause is a long run-on that could be split for scanability.

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

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

There is no output schema, and the description compensates by describing the returned payload fields and their 300-char truncation. With no annotations, it also warns that results are state-diffed and may contain noise on busy pages. Complete enough to call correctly; only timing/teardown semantics are unstated.

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

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

Schema description coverage is 100%, so both `ref` and `session` are already documented in the schema, including the concurrency rationale for multi-session dispatch. The description only echoes 'by ref' and adds nothing about the session parameter. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (hover) on a specific resource (element by ref) and immediately enumerates what it returns: tooltips/popovers diffed against pre-hover state, new page text, title attribute, and aria-describedby. It is clearly distinguishable from scout_click and scout_snapshot, which it implicitly contrasts by noting hover-gated UI is invisible to 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?

Gives concrete application targets (badges, icons, truncated text, error indicators) and a strong directive: use BEFORE concluding an element 'does nothing'. It also clarifies the boundary condition that hovering does not count as exercising the element. It stops short of naming an alternative tool explicitly, but the snapshot/click contrast supplies the routing context.

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

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

Adds real behavior beyond the annotations: the form flow, the second confirmation form when the care level requires it, the exact return shapes (plan with guidance then ordered calls, or four plain questions), and two safety statements ('Never asks for a password', 'Touches no browser'). It leaves the non-idempotent, non-read-only character implied rather than stated, so it isn't fully transparent about what state the intake creates.

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

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

One dense paragraph that front-loads the trigger condition and then walks through the branches in the order an agent will encounter them. Slightly run-on ('how they sign in, how careful to be and how thorough'), but no sentence is expendable.

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

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

There is no output schema, and the description fully covers both possible returns and the two-form interaction sequence. An agent knows what it will get back and what it must do next in either branch.

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?

With one parameter at 100% schema coverage the baseline is 3, but the description adds meaning the schema does not: the url is optional and pre-fills the form when the person already stated the address. That is a genuine behavioral note about how the parameter is consumed.

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 action: elicit the person's checking preferences when no settings were given, then build a guided plan. It distinguishes itself from siblings like scout_guided_plan and scout_guided_confirm by describing the two-form flow and the chat fallback. The opening phrase 'Ask how the person wants their site checked' is slightly indirect as a verb+resource statement, but the rest of the description pins the purpose down.

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 clear entry condition ('when they gave no settings') and describes the branch taken when the client cannot render a form or the person declines/closes it. It does not explicitly name a sibling alternative (e.g. scout_guided_plan) for the case where settings already exist, which keeps it out of the top band.

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 behavioral burden. It transparently lists what is returned (interaction cost, path, friction signals like BACKTRACKS, screen count, over-interaction) and warns that shortcuts invalidate the measurement. It does not explicitly state whether the tool modifies the application or requires specific permissions, but its description as a measurement wrapper implies read-only 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?

The description is a single, well-structured paragraph that front-loads the core purpose and then provides necessary operational details. Every sentence contributes useful information, though it could benefit from minor formatting (e.g., bullets) for readability.

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 (a measurement wrapper with start/end lifecycle), the description covers the essential workflow, return values, and usage frequency. It omits details about the session parameter's concurrency behavior, but the schema compensates. No output schema exists, yet the description adequately explains the return format.

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 all five parameters. The description restates the start/end usage pattern with goal and completed, but adds no new meaning beyond what the schema provides for parameters like session or note. 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?

The description opens with a specific verb+resource: 'Measure how EASY a real task is' and explicitly contrasts this with pass/fail e2e suites. It then details the start/end wrapper pattern with concrete examples, making it unambiguous what the tool does and how it differs from simple pass/fail testing.

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 when to use the tool ('Run it on each module's primary journey') and gives a crucial usage constraint ('navigate by CLICKING through the UI, not by jumping to a known deep URL — a shortcut invalidates the measurement'). However, it does not explicitly name alternatives or when not to use it, leaving some inference to the agent.

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

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

With no annotations, the description carries the full burden and does disclose the important traits: it touches no browser, the split is whole-modules balanced by route count, and the split guarantees no overlapping lanes and no unopened routes. It does not cover failure modes such as the saved-role login-expiry refusal, which only appears in 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?

The core action and the lane-isolation guarantee are front-loaded, and the sequencing guidance follows without filler. The opening fragment ("For a run split across parallel agents (lanes).") is slightly abrupt, but no sentence 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 coordination tool with 8 parameters and no output schema, the description usefully describes the return payload (session name, objective, owned routes) and the no-browser contract. Minor gaps around refusal/error behavior are acceptable since the schema documents the triggering parameters.

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 every parameter including fromRun, fromRunMode, runMinutes, and expiryMarginMinutes is already documented in structured data. The description only reinforces the meaning of `lanes` (N lanes) and the default route set. This is the expected baseline when the schema does the heavy lifting.

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

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

States a concrete verb and resource: divides the app's known routes between N lanes and returns each lane's session name, objective, and owned routes. It also explicitly separates itself from scout_lane_report, which handles what the lanes hand back, so an agent can pick between them without opening either schema.

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

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

"Call it after the first crawl, when route knowledge is complete" gives the precondition, and the closing sentence routes the agent to scout_lane_report for the reverse direction. It also tells the agent what to do with the output (pass the briefs to lane agents) rather than call this tool itself for browsing.

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 burden and does well: it discloses the return payload for both modes (prompt paragraph vs. fold of defects/highs/unsure/mean confidence/routes), states that refusals come back with a reason, and closes with "Touches no browser" to rule out side effects. It omits whether lane names must be unique or how malformed replies are handled, but the safety profile is unambiguous.

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 scope condition ("For a run split across parallel agents") then split cleanly into without-`reply` and with-`reply` cases. The parenthetical enumerations of fold contents are dense but each item is informative. Slightly crowded phrasing keeps it off a 5.

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

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

No output schema exists, so the description must describe returns, and it does for both modes including the refusal path. For a 2-parameter, single-purpose coordination tool that is nearly complete; only edge-case behavior (invalid lane, unparseable reply) 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 coverage is 100%, so the baseline is 3, but the description adds real semantics: `reply` is "the text the lane handed back" and omitting it flips the tool into instruction mode, which is richer than the schema's own wording. `lane` gets no extra detail beyond the schema's "as used in its session".

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 mechanism: with no `reply` it produces the instruction paragraph for a lane's prompt, and with `reply` it parses the lane's return and folds it into a one-line summary. That is a concrete verb+resource statement for a two-mode tool. It stops short of naming the sibling it should be chosen over (e.g. scout_lane_brief), so an agent must infer the boundary from context.

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

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

The two branches are explicitly conditioned on the presence of `reply`, which is exactly the decision an agent needs to make when calling this tool. It also states the fold result is "to relay to the lane once", implying a single-use handoff. No explicit when-not guidance or named alternative 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, the description carries the full burden and does: it discloses that the window closes on its own, that an SSO round trip is followed rather than treated as completion, that closing the window saves nothing, that the agent must never type credentials, and that the call can return with the window still open. It also flags the desktop/display prerequisite that would otherwise cause a silent failure.

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

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

Purpose and the when-to-use trigger are front-loaded, then the user-facing instruction, then the save/return semantics, then the display caveat. It is dense but nearly every sentence carries operational information; the only mild cost is length, which makes the critical 'never type credentials' and 'closing saves nothing' points harder 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?

There is no output schema, so the description must explain what the call returns, and it does ('Returns once signed in and saved, or after waitSeconds with the window still open'). Combined with the desktop caveat and the credential-handling rule, nothing an agent needs in order to call this safely 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 3 is the baseline, but the description adds real meaning beyond the schema: role is the key scout_attach consumes, successUrl is only relevant 'when the user says how to tell', and waitSeconds governs whether the call returns with the window still open. url and browser are left to the schema, which already covers them 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 states a specific verb and resource ('Open a visible browser window for the USER to sign in to the app as a role, and save that sign-in') and ties the artifact to a named consumer, scout_attach { role }. That linkage alone separates it from every other sibling in the list.

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 ('when an attach is refused because no sign-in is saved for the role, or the saved one has expired') and an explicit fallback for the no-display case (run `scenescout login <url> --role <name>` where the window is visible). It also names the retry pattern: call again with the same role to keep waiting.

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

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

With no annotations, the description carries the full behavioral burden and does add useful context: paths resolve from the origin root regardless of the current page, and full URLs must be on the attached origin. However, it does not describe navigation timing, failure behavior, or other side effects, leaving meaningful gaps.

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

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

Two short sentences, front-loaded with the core action, then the path-resolution rule, then the back alternative. Nothing is wasted.

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

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

The schema fully documents all five parameters, including task, leave, and session semantics, and the description covers the target behavior and back alternative. It is sufficient for correct invocation, though it does not discuss post-navigation state or error handling.

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

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

Schema coverage is 100%, so the parameter documentation baseline is 3. The description goes beyond the schema's simple '/settings' example by explaining that paths resolve from the origin root whatever page the session attached on, and that full URLs must be on that origin.

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

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

The description states a specific verb and resource: navigate to a path on the attached origin or a full URL on it. It also distinguishes the back behavior by naming scout_back as the sibling to use instead. An agent can tell what this tool does without opening the schema.

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

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

It clearly establishes the navigation context and points to scout_back for going back. It does not explicitly exclude other navigation-adjacent approaches like clicking links, but the intended usage is clear enough.

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 states read-only behavior, explains that it sends nothing, notes credential redaction in query strings, clarifies that a full page load resets the list, and marks scout_request's own calls.

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 front-loaded with the core purpose and then adds usage and safety context in a tight paragraph. Every clause carries useful information, with no redundant restatement of the schema.

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

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

Given the absence of annotations and output schema, the description provides enough detail to call the tool correctly: it describes the return fields, ordering, route marking, redaction, session-reset behavior, and diagnostic use cases.

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 limit, session, and contains in detail. The description adds no parameter-specific guidance beyond the schema, which is the baseline expectation when coverage is complete.

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

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

The description names a specific resource and scope: data requests (fetch and XHR) made by the current page since document load, including method, path, status, time, and route origin. It also differentiates this from sibling scout_request by noting that scout_request's own calls are marked.

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 diagnostic scenarios: when the page and server disagree, such as an empty list where the API has data or a stale value after save, and explains that it distinguishes failed, pending, and never-run requests. It stops short of naming when not to use it or explicitly pointing to an alternative tool beyond the scout_request marking note.

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 much of it: notes are dated, attributed to the acting role, deduplicated, persisted across runs, and the setup section is read back by the engine on storage-state expiry. It omits whether notes can be edited or removed once written, and whether read returns the whole file or one section.

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 in the first two sentences, but the rest is a single dense run-on paragraph with nested em-dash asides and inline JSON examples that duplicate the schema. Every claim is relevant, yet the readability cost is real compared with a short bulleted section list.

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 carry return expectations; it conveys that read yields human-readable prose and enumerates the section taxonomy, which is enough to call it correctly. What read actually returns (whole file vs. a section) 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 coverage is 100% and both enums already document their values, so the baseline is 3. The description goes somewhat beyond the schema by explaining what belongs in each section in prose (persona inference for roles, examples for constraints), but the note format and session parameter behavior 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?

Names a specific resource (.scenescout/ASSUMPTIONS.md), its content type (cumulative written knowledge about the tested app) and explicitly contrasts it with memory.json ('memory.json stores coverage; this stores UNDERSTANDING'). It does not distinguish itself from the nearest sibling, scout_playbook, which is the one an agent could plausibly confuse it with.

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 when-to-use ('READ it at the start of every session'), when-to-add ('ADD durable learnings as you go'), and an explicit exclusion ('Do NOT record session-specific facts (ids, counts) — only durable knowledge'). Each of the seven sections is named with the condition that selects 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 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, the description carries the full burden, and it does disclose the observable effect (dismisses modals) and example key values. It says nothing about whether the target element must have focus first, whether modifier combos are supported, or what happens if the key is invalid, which are real failure modes for a keypress 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?

One front-loaded sentence with the action first, examples second, and rationale last. No filler, though the modal example and the navigational example are slightly redundant for such a small tool.

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

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

For a four-parameter tool with no annotations and no output schema, the description is thin: it omits focus requirements, whether the press is dispatched to the page or a specific element, and what the tool returns or reports. The schema covers the harness parameters, but the actual behavioral contract of pressing a key is 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 75% and the richly documented task/session/objective parameters are already fully explained in the schema. The description's only added parameter value is clarifying that `key` expects a named key such as Escape/Tab/Enter, which is useful since that field has no schema description, but it never addresses multi-key sequences or modifiers.

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

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

States a concrete verb and resource (press a keyboard key) and supplies representative values (Escape, Tab, Enter) so an agent immediately knows the operation. It does not distinguish itself from the nearest sibling, scout_type, which also sends keyboard input, so the boundary is left implicit.

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

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

Gives two concrete situations where this is the right call: closing modals and testing keyboard navigation. It never says when NOT to use it or names scout_type/scout_click as alternatives, so the agent must infer that typing text belongs elsewhere.

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

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

Goes well beyond the annotations: it explains the write side effect that justifies readOnlyHint=false (`.scenescout/recap.svg` when save is true), declares an error condition (refuses with no ended check), clarifies the data source ('built from the check's figures only'), and rules out browser activity. These are exactly the operational facts an agent needs before invoking.

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 payload contents are front-loaded, then outputs, then side effect, then preconditions — a logical order with no filler. Slightly list-heavy but each clause carries information.

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

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

Even though an output schema exists, the description still tells the agent what comes back (SVG plus text lines) and covers preconditions, side effects, and data provenance. Nothing needed to call it correctly 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?

Only one parameter at 100% schema coverage, and the schema already documents `save` identically. The description restates the same effect rather than adding format or failure details, so it hits the baseline.

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

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

States a specific artifact (the recap card of the guided check that just ended) and enumerates its contents — address, pages checked, problems by impact, confirmed fixes, elapsed time. That scopes it apart from scout_team_report and scout_lane_report without naming them explicitly.

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

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

The precondition 'Refuses while no guided check has ended' plus 'for the person to share with their team' makes the timing and audience clear. No explicit exclusion or named alternative (e.g. scout_team_report), 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?

Adds behavior beyond the annotations: each call yields a NEW plan so prior confirmations do not carry over and scout_guided_confirm must ask again, and the tool touches no browser (consistent with readOnlyHint). That non-idempotent, no-side-effect-on-site profile is exactly what annotations alone could not convey.

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 in the first sentence and every clause carries information (scope limits, confirmation semantics, follow-up flow, defaults). It is dense and runs long as a single paragraph, which slightly hurts scannability.

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 an output schema, full param coverage and annotations already present, the description supplies the remaining decision-critical context: care-level scoping, cross-site exclusion, confirmation reset, and sequencing with scout_attach/scout_verify. Nothing needed to invoke it correctly 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 ids, signIn and address, and the description's default rule largely restates the ids default. It does add one thing the schema lacks: ordering ('worst route first', at most 25) and the site-scoping effect of address, but that is marginal against a fully documented 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: build a guided re-check plan over problems earlier checks left open, classifying them as gone, still there or changed. This is clearly separable from scout_guided_plan (fresh check) and from per-site or looser-care-level re-checks it explicitly excludes.

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

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

Explicitly scopes the call to the care level where problems were found and says what is NOT handled here ('problems found in a looser care level are left for a re-check of their own, and problems on another site for a re-check of that site'). It also prescribes the follow-up flow (attach with planId, then scout_verify) and names scout_guided_confirm as the confirmation path.

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 the write target (.scenescout/report.md), why the return is a bounded summary (full reports exceed client token limits), and the refusal-as-completeness-guarantee behavior. That is exactly the contract-level detail an agent needs before invoking.

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 what and outputs in the first sentence, then the gating rules. Dense with parentheticals and caps and slightly long, but nearly every clause conveys actionable contract detail rather than filler.

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

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

No output schema exists, yet the description explains the return (bounded summary vs. full file), the file side effect, and the gating contract that governs successful invocation. Nothing an agent needs to call this correctly 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, and the description goes beyond it by explaining the enforcement semantics of `level`, the constrained role of `force` ('only when the user capped the budget'), and the report/history tradeoffs. It reinforces rather than duplicates the schema, though not every parameter is addressed in the prose.

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

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

States a specific verb ('Generate') and resource ('the final markdown report') and enumerates the exact contents: findings, page quality scores, role capability matrix, oracle rollup, and gap ledger. It is clearly the terminal report tool, though it never names siblings like scout_lane_report or scout_recap to draw the boundary.

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 describes the level-gated completion contracts and the refusal condition ('extensive REFUSES while the gap ledger is non-empty'), plus the force override only when the user capped the budget. Strong when/when-not guidance, but it does not point to any alternative tool for partial or intermediate reporting.

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, and the description carries the whole load: cookies and the app's last Authorization header ride along, requests pass through the same interception the write policy enforces, safe-write may refuse a mutation on a record the session did not create, and that refusal is explicitly labeled a safety net rather than a finding. Side effects (recorded in the run trail, signature quotable by a finding) and edge behavior (paths fenced to the origin) are all disclosed.

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, and nearly every sentence adds information. The aphorism 'A button that is not shown proves nothing; the same action refused by the server does' is justification-flavored prose in an otherwise dense single paragraph.

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 10-parameter tool with no annotations and no output schema, the description still covers what comes back — status line, timing, the specific comparison-deciding headers, body truncation at 2000 characters with select/offset alternatives, and the next-offset hint. Nothing an agent needs to call it correctly or interpret the result 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 every parameter is already documented — including select paths, offset/limit windows, headers overriding the app's own, and method-override policy. The description restates the body-window behavior and header precedence but adds essentially no semantics the schema does not already carry, 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 specific verb and resource — call the app's own API as this session — and immediately fixes the scope: UI bypassed, run in-page, fenced to the attached origin. An agent can distinguish it from scout_click (UI actuation) and from a shell call without opening the schema.

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

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

Gives the decisive selection criterion — a hidden/disabled control proves nothing, a server refusal does — and the host-fencing exclusion ('use another session to reach another host'). It never names scout_click or scout_navigate explicitly as the alternative for normal interaction, so routing is inferred 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, the description carries the behavioral burden and does well: it discloses the state transition (moved to the Resolved section) and the non-obvious reversibility (auto-reopens as REGRESSIONS if re-found). It omits auth/permission needs and what the call returns, keeping it short of a 5.

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

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

Three tightly packed sentences: action first, then effect/side-effect, then usage trigger. No filler and the most important fact (the id source) 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?

There is no output schema, and the description adequately explains the resulting state and the regression side effect. It leaves minor gaps—what happens with an unknown id and why/when to pass the optional `session` parameter—but nothing that would cause a mis-call in normal single-session use.

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 supplies baseline meaning. The description adds provenance for the id ('shown when recorded and in the report'), which tells the agent where to obtain a valid value—more than the schema alone 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 ('Mark a finding as resolved') plus the identifier needed to do it. It also names the observable outcome (moves to the report's green ✅ Resolved section), which distinguishes it from recording tools like scout_finding or scout_recheck_plan.

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 triggering conditions: 'when the user says a bug is fixed' or 'when re-testing shows the evidence no longer reproduces.' That is clear usage context, though it never states when not to use it or names alternative tools for the adjacent recording/re-testing workflows.

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

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

With no annotations, the description carries the full burden and does so: it states the plan aborts at the first NEW violation, policy refusal or failed step, that repeat violations do not abort, that 'continue' only tolerates new http_error/console_error while failed steps and policy refusals still stop, and that a bad select value fails immediately listing options. It also discloses that targets resolve at execution time and that plans can be replayed by `scenescout check` in CI.

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 one-call/20-action hook and the use case, then ordered by importance: locators, CI replay, upload, abort semantics, continue mode. It is dense and long for a description, with some detail (the `scenescout check` PR-replay digression) that is orientation rather than invocation guidance, but almost no sentence is filler.

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

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

No output schema exists, and the description compensates by describing what comes back on failure ('returning a transcript of how far it got') and how errors are surfaced per step. For a 20-step batch tool with no annotations, the failure modes an agent must reason about (abort vs. continue, select-option mismatch, upload target requirement) are all covered.

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

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

Schema coverage is 80%, so the schema already documents most fields; the description still adds real meaning — execution-time semantic locator resolution and the 'never snapshot refs' prohibition, and that upload's value is a fixture kind or project-relative path with a required target. It adds nothing for `task`, `objective` or `session` beyond what the schema says.

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

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

Opens with a specific verb, scope and batching rationale: 'Execute up to 20 actions in ONE call'. This unambiguously separates it from the single-action siblings (scout_click, scout_type, scout_select, scout_hover) and from scout_guided_plan / scout_recheck_plan.

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 clear trigger ('mechanical sequences (fill a form, walk a wizard)') and an explicit alternative condition for the onViolation "continue" mode ('a sweep of independent steps (tabs, filters, pages)'). It does not explicitly say to prefer scout_click for one-off actions or reference the sibling plan tools by name, so routing vs. scout_guided_plan / scout_journey is left implicit.

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

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

Adds substantial context beyond the annotations: on-disk location (.scenescout/guided/), owner-only readability, an explicit guarantee that no password/code/token/cookie is stored, that delete touches one file and nothing else, that run produces an unaccepted plan, and that the tool "touches no browser." This makes the destructiveHint=false annotation coherent. A minor gap remains: nothing says what happens when "save" reuses an existing name, which matters given idempotentHint=false.

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 action set and the definition, then action-by-action behavior — no filler sentences. The parenthetical definition of a saved check is long, and the planning-flow sentences (run/confirm) are dense, but each carries distinct information an agent needs.

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

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

With an output schema present and annotations covering the safety profile, the description supplies exactly what structured fields can't: storage/privacy semantics, per-action preconditions, the address fallback for folder resolution, and the handoff to scout_guided_confirm/scout_guided_plan. Nothing needed to invoke it correctly 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 every parameter is already documented in the schema, including the action enum and the address fallback. The description adds the cross-parameter coupling (name+planId only for save, address only when no check is open), but repeats rather than extends most per-parameter detail. Baseline 3 applies when the schema carries the load.

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 four specific verbs (list, save, run, delete) over a named resource (the person's saved guided checks) and immediately defines what a saved check is — the choices of a guided plan under a name. It also distinguishes this from the re-check path ("a re-check is not saved") and from scout_guided_plan, so an agent can route 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 per-action conditions ("save" needs name+planId, "run"/"delete" take the name), names the alternative tools for the downstream flow (scout_guided_confirm asks for confirmation, then follow as scout_guided_plan), and states the prerequisite for resolving the folder via address when no check is open in the conversation. Explicit when-to-use and cross-tool routing.

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

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

No annotations are supplied, so the description carries full behavioral burden. It discloses the outputs discovered, which implies a read-only inspection, but never states that it makes no writes, whether results are cached/persisted for later tools, roughly how long it takes, or what happens on a non-frontend project. Adequate but leaves real gaps for a first-step tool.

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

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

Two sentences, zero filler. The action and discovered artifacts come first and the ordering constraint ('Run this first') is front-loaded at the end where it is most actionable.

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

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

With no output schema, the description usefully enumerates the categories of information returned, which is what an agent needs to decide to call it. Minor gap: no note on how the results are consumed by downstream tools like scout_playbook or scout_run_plan.

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

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

Schema coverage is 100% and the single parameter projectPath is fully documented in the schema as an absolute path. The description adds no meaning beyond that, so baseline 3 applies.

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

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

States a specific verb (scan) and resource (project directory) plus an explicit inventory of what the scan discovers: frontend workspace, framework, routes, dev command, Playwright auth storage states, testid conventions. No sibling tool does discovery scanning, so it is easily distinguished in a 46-tool namespace.

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?

'Run this first' gives a clear ordering directive relative to all the other scout_* tools, which is strong guidance for a discovery tool. It stops short of naming explicit exclusions or alternatives (e.g. when to use scout_recheck_plan instead of a fresh scan).

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

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

With no annotations, the description carries the full behavioral burden. It discloses the output format (JPEG), the scope (current viewport, not full page), and the fact that it should not be used for geometry, broken images, or style issues. It does not mention latency, waiting for load, or whether the screenshot can fail, but the core behavioral profile is well 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?

The description is front-loaded with the core action, then immediately states the LAST RESORT constraint and routes to the correct siblings. Every sentence earns its place and zero words are 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?

Given one optional parameter, no output schema, and no annotations, the description is nearly complete. It covers use case, alternatives, and output scope. A small gap remains around operational behavior such as waiting for load or handling screenshot failures, but the essential guidance is present.

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 semantics beyond what the schema already provides; 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?

Names a specific verb and resource ('Take a JPEG screenshot of the current viewport') and explicitly distinguishes the tool from sibling alternatives. An agent can immediately tell this is for pixel-native content, not DOM or style analysis.

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 labels the tool as a LAST RESORT, names scout_snapshot for geometry and broken images, scout_design_audit for style/contrast/spacing, and states the only appropriate use case: pixel-native content such as a canvas or visual gestalt. When-to-use and when-not-to-use are both clear.

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

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

No annotations exist, so the description carries the load and does it well: it discloses the return payload (px and %), the SCROLL LOCKED flag with its cause, the OVERLAY cross-reference, and that scrolling triggers lazy-loaded content whose failures surface as oracle violations. It stops short of stating timing/settle behavior or what happens if the target has no scrollable ancestor.

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

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

Front-loaded with the purpose and the key failure mode, then target semantics, then the workflow rule. Several long parenthetical digressions about leaked modals and truncated nav content are dense but mostly earn their place; a tighter edit would cut roughly a fifth.

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 the description nevertheless explains what comes back (px and % plus the scroll-locked flag). For a 4-parameter, zero-required navigation tool, everything needed to call it correctly and interpret the result is present.

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 3 is the floor, but the description earns more by explaining the consequence of target: it scrolls the element's nearest scrollable ancestor and exists precisely because the page-level pick is the largest scroll port. That semantic linkage (why a smaller region appears truncated) is not 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?

Names a specific verb and resource ('Scroll like a user') and immediately scopes it against the passive alternative — snapshots detect scroll-lock, this tool actively scrolls. An agent can distinguish it from scout_snapshot and scout_design_audit without opening either schema.

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

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

Explicit sequencing rules: use before judging a long page, scroll then re-snapshot/re-audit, and 'never call a nav item missing without scrolling its own container first.' It also states when to omit target (page-level default with app-shell fallback) versus when to pass 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 the entire matching precedence (exact value, exact label, case-insensitive variants, label prefix) and the failure mode (refused immediately, with the available options listed back). It stops short of saying whether the call is atomic or what happens if the select is disabled/hidden.

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

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

Two sentences, front-loaded with the action, then the matching algorithm, then the error contract. Every clause carries information; nothing is repeated from the schema or title.

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

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

For a two-required-parameter action tool with no output schema and no annotations, the description covers the operation, resolution semantics, and failure behavior. It omits any mention of the shared `task`/`session` boilerplate, though the schema documents those at length, so that 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 coverage is 80%, so the baseline is 3. The description goes beyond the schema by spelling out the resolution order for `value`, which the schema only gestures at with '(or the start of a label, when only one option has it)'. The `ref` parameter is left unelaborated.

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.' It clearly delineates the domain (native select elements) which separates it from the general-purpose scout_click sibling. An agent can immediately tell what this tool is for.

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

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

The description implies when to use it (native <select> elements, addressed by ref) but never names an alternative such as scout_click for custom dropdowns, nor states preconditions like the element needing to be in the snapshot. Usage is inferable rather than explicit.

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

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

With no annotations, the description carries the full burden and delivers non-obvious behavioral facts: setting a default has no side effect on liveness or auth state, both browsers stay authenticated regardless of which is default, and a re-snapshot is needed to see what changed while a session was away. It does not say whether the default persists across calls/connections or what the listing returns.

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

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

Front-loads the two primary behaviors in the first clause, then qualifies with the preferred alternative. Dense but mostly earning its words; the parenthetical asides and em-dash clauses make it slightly rambling relative to the core message.

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

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

No output schema and no annotations, so the description must hold the whole story — and it leaves out the pacing and guided-area functions entirely, plus any indication of what a listing returns. What it does cover (default-session semantics, liveness guarantees) is complete and correct.

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. The description adds genuine meaning for `name`/`session` by framing them as 'the session every unqualified call falls back to', which is more than the schema states. But `paceMs` and `area` are never mentioned in the description at all, so it contributes nothing for two of the four parameters.

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

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

States two specific verbs (list live sessions, set the DEFAULT session) on a named resource, and explains that omitting `session` elsewhere routes through the default. It is clearly distinguishable from siblings like scout_status. However, it covers only two of the tool's four capabilities — nothing signals that this same tool also throttles action pace (`paceMs`) or marks the current guided area (`area`), so the stated purpose under-describes the tool's scope.

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

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

Explicitly names the preferred alternative (pass `session` directly on each call for multi-role/concurrent work) and characterizes this tool's niche as sequential convenience plus introspection. That is real when/when-not guidance against a concrete alternative. It stops short of when to use the pace-throttling and area-tracking modes.

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 diffing semantics, ref stability across query-string rewrites, cross-tab diffing behavior, element-cap truncation messaging, and relative cost. These are meaningful behavioral traits 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?

The description is front-loaded with the core action and every clause adds substantive detail about return contents or behavior. It is somewhat dense as a single paragraph and could be easier to scan, but there is no empty 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 is provided, so the description must explain return values, and it does so thoroughly: URL, fingerprint, summary, refs and states, announcements, geometry issues, coverage, oracle violations, diff behavior, and truncation. For a two-parameter snapshot tool, an agent has enough 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 both parameters are already fully documented in the schema. The description implies diff-vs-full behavior but does not add syntax, format, or concurrency details beyond what the schema provides, 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: capture the current page state, with a precise inventory of what the snapshot contains (URL, fingerprint, heading/text summary, interactable elements with refs and state, announcements, geometry issues, coverage, oracle violations). It also distinguishes itself from the obvious sibling: 'Cheap — prefer this over screenshots.'

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

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

Names the key alternative ('prefer this over screenshots') and explains the important diff-on-re-snapshot behavior, which implies repeat snapshots are expected. It does not give explicit exclusions or prerequisites, so it falls short of the top score but gives clear contextual guidance.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses that it takes no input and touches no browser (implying a safe, side-effect-free read), and explains host-dependent behavior (MCP Apps pane vs plain text with a `Live view:` address to relay). It does not mention rate limits, caching, or freshness guarantees for the status data.

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 purpose is front-loaded, but the middle stretches into a long, loosely punctuated run-on ('problems so far and the newest cards, and the clicking it saved with what that figure is based on') that is hard to parse. Information density is high but scannability suffers.

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 output schema and no annotations, the description does the work of describing the returned content (session objectives, task, findings by severity, coverage, live view address, guided-check progress). This is nearly complete for a no-arg status tool, though output field shapes remain informal rather than structured.

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

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

The tool takes zero parameters and the schema is empty, so the baseline is 4. The description correctly confirms no input is required, leaving no ambiguity about arguments.

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

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

The description states a specific verb and resource (show run status: session objectives, findings by severity, coverage, live view address) and enumerates what is included, which lets an agent distinguish it from most siblings. It does not, however, differentiate itself from the sibling scout_status_poll, whose name suggests near-identical purpose.

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 trigger conditions: call it when the user wants to watch or asks how the run is going, and it clarifies the guided-check variant. No exclusions or routing between this and scout_status_poll are given, so the when-not side is missing.

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 annotations already covering the safety profile, the description still adds substantial behavior: exact write scope (.scenescout/, team-report.html and team-report/), replacement of the prior team report (confirming the idempotentHint), the contents of the adjacent evidence folder including SHA-256 manifest, and explicit 'sends nothing anywhere and touches no browser' (reinforcing openWorldHint=false). This is unusually complete disclosure of 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?

Purpose is front-loaded, but the second and third sentences are long laundry lists enumerating report sections and folder contents. Much of that inventory is plausible detail, yet it slows the agent scanning for the decision-relevant facts (what is written, where, and that nothing is sent).

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?

An output schema exists, so return values are already documented, and the description still supplies everything the agent needs to explain the artifact to the user: the file path, the folder layout, and the exact side-effect boundary. Nothing material for calling this zero-arg tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. No parameter-like inputs are exposed or implied, correctly matching the empty schema.

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

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

States a specific verb+resource (writes the team report page) and describes the artifact concretely, including that it is 'the plain report made for sharing'. It does not name the sibling it differs from (scout_report, scout_lane_report), so the agent must infer the team-vs-lane distinction, but the purpose itself is unmistakable.

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

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

Usage is only implied by 'the plain report made for sharing' and the closing 'Tell the person where the page is'. There is no explicit when-to-use or when-not-to-use statement and no named alternative among the many report-producing siblings (scout_report, scout_lane_report, scout_coverage).

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

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

Adds rich behavior beyond the annotations: a human confirmation form gates the write, nothing the caller passes can confirm it, filing requires a preview under 10 minutes old and unchanged problems, refusals occur otherwise, and previews are single-use. It also scopes side effects ('Touches no browser') and return content, which the readOnly/openWorld annotations alone could not convey.

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 action and its dependency, then the consent gate and failure modes. Nearly every sentence carries a distinct constraint, though the middle block is dense enough that an agent must parse several conditions in one clause chain.

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 non-idempotent write gated on human consent, the definition covers prerequisites, freshness, refusal behavior, single-use semantics, and return value ('each filed ticket's link'), which complements the existing output schema. Nothing needed to invoke it safely 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% and the single previewId is documented there, so the schema carries the baseline. The description still adds meaning the schema lacks: that the id must come from scout_ticket_preview, that it is consumed once, and that it expires after 10 minutes.

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

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

Opens with a specific verb and resource ('File the tickets a preview from scout_ticket_preview listed') and explicitly ties itself to the sibling that produces its input, so an agent can distinguish it from scout_ticket_preview, scout_tickets, or scout_ticket_status without reading schemas.

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

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

States exactly when to call (after a preview lists tickets), what the agent may and may not do ('You may make this call; you cannot answer the form'), and the negative cases where it must never be called again ('turns the form down or closes it, or this client cannot show forms'). The alternative path ('a new preview is needed') is named explicitly.

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

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

Annotations declare readOnlyHint and openWorldHint, and the description goes well beyond them: it says the tracker is read to detect markers, that nothing is sent, that a previewId expires after 10 minutes, that over-limit items are surfaced, and that no browser is touched. Credential sourcing (GH_TOKEN/GITHUB_TOKEN, JIRA_EMAIL/JIRA_API_TOKEN from env or desktop settings) is disclosed too.

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 preview/read-only guarantee and the file-this-later handoff before dipping into parameter and credential detail. Mostly tight, but the mid-sentence splice starting with 'to: "github" with target...' reads as a run-on fragment rather than a clean clause.

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

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

An output schema exists, yet the description still summarizes what comes back (tickets that would be filed, ones already filed, over-limit, previewId) so the agent knows the shape of the decision surface without parsing the schema. For a read-only preview with three required params, nothing material 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 3 is the baseline, but the description adds real meaning: it ties `to` values to the shape of `target` (owner/name for GitHub, project key for Jira) and reveals where the Jira site comes from (JIRA_BASE_URL in server settings). `ids` is only loosely characterized ('the problems the person chose'), leaving the schema to carry the maxItems/format detail.

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

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

Opens with a specific verb+resource: 'Preview filing the problems the person chose as GitHub or Jira tickets.' It is cleanly distinguished from the sibling scout_ticket_file, which is named as the follow-up step, so an agent cannot confuse the dry-run with the write.

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

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

States exactly when to call it ('show the person the list') and the alternative path ('to file it, call scout_ticket_file with the previewId'). It also gives explicit negative guidance about credentials: never ask the person for a token and never pass 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?

No annotations are supplied, so the description carries the full burden and does substantial work: it enumerates the recognised formats (Given/When/Then, checklists, numbered, 'AC1:', headings), declares the no-guess fallback for unrecognisable tickets, and states what is returned (criterion ids). Gaps remain around whether repeated calls replace or accumulate previously loaded tickets and what happens with a path outside the permitted dirs.

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 input sources are front-loaded, and the format-recognition and criterion-id details each carry real decision value. It is a single dense paragraph, though, and the format enumeration could have been compressed without losing 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?

With no annotations and no output schema, the description has to explain both behavior and result, and it does: input sources, parsing rules, the unrecognisable-ticket outcome, and the criterion-id return shape. Only the persistence/replacement semantics of repeated calls are left unstated.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the text-vs-path exclusivity and the multi-session concurrency semantics for `session`. The description adds only the paraphrase 'pasted (`text`) or from a file (`path`)' and the multi-ticket note, 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 (read tickets/acceptance criteria) plus the effect (keep them so the report answers each criterion). It distinguishes itself from scout_criterion by naming it as the follow-up consumer and from the ticket_* siblings by scope ('the person gave this run'). An agent can tell what it does 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?

Clear operating context: use it on the tickets supplied for this run, with either pasted `text` or a file `path`, and multiple tickets may be passed at once. It routes the next step explicitly ('judge it by with scout_criterion') and draws a boundary ('Touches no browser'). It stops short of naming when to prefer scout_ticket_preview/scout_ticket_file instead, so a 4 rather than 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?

Beyond the annotations, it discloses the 5-minute-per-project read throttle, the stale-response behavior (fresh: false plus next read due), that only the tracker the server settings point at is read, credential sourcing from the environment, and that it sends nothing and touches no browser. This is exactly the operational context annotations alone cannot convey.

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 what and the throttling/freshness caveat are front-loaded, and every sentence carries substantive information. It is dense and the parameter guidance is appended after the behavioral notes, which is slightly less efficient but still well organized.

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?

An output schema exists, so return values need not be spelled out, and the description still covers freshness, caching, tracker selection, and auth. Nothing an agent needs to invoke it correctly 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?

With schema coverage at 100% and a single parameter, the schema already documents address. The description restates the same condition ('when no check is open in this conversation, pass the site's address') without adding format or sourcing detail beyond the schema, 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 specific verb (list) and resource (tickets filed by this project) plus what the return contains: tracker open state and whether the problem is still open. It names the sibling that files tickets (scout_ticket_file / export), so an agent can distinguish reading status from creating tickets.

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 clear context for use (checking whether filed tickets/problems are still open) and an explicit conditional for the single parameter: pass the site address when no check is open in this conversation. It does not explicitly contrast with scout_tickets or scout_ticket_preview, so alternatives are only implicit.

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

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

With no annotations, the description carries the full burden and does so: it discloses append-vs-clear semantics, that appending fires input events but not keydown, that the result reports prior content, the word-boundary space rule, and that secret-field values and prior contents are masked in both result and log. Those are non-obvious side effects an agent could not get from 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?

Every sentence carries real information and the default (append) behavior is front-loaded before the replace exception. It is a single dense paragraph, though, and the masking sentence runs long enough that splitting it would aid scanning.

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

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

There is no output schema, and the description does cover what the result reports (prior content, masking). It is nearly complete for an 8-parameter mutation tool with no annotations, but is silent on failure modes such as an unresolvable ref or an element that is not an editable field, and never states that refs come from a snapshot.

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 modest meaning for `replace` ('correcting a previous entry') and an implicit empty-value rule for textValue, but says nothing about `pressEnter`, `task`, `session`, or the `value`/`objective` aliases beyond what the schema already documents.

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

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

States a specific verb (type) and resource (text input/textarea/composer) plus the addressing mechanism (by ref), and frames it as 'the way a real user does' to distinguish it from scripted value-setting. An agent can separate this from scout_press, scout_select, and scout_click without opening any schema.

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

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

Gives concrete conditions: append by default to preserve existing content, pass replace=true to correct a prior entry, empty textValue clears, and 'use for both valid values and boundary/fuzz values'. It also warns that keydown-driven slash/mention menus will not react to appended text, which implicitly routes that case elsewhere, but it never names scout_press as the alternative, leaving the agent to infer 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: it discloses that fixtures are generated in memory and are structurally valid, that filePath is fenced to the project, that credential-shaped paths (.env, .ssh, *.pem, etc.) are refused unless the operator listed them, and that it warns on accept mismatches and cleared inputs. It also reports whether a state-changing request fired, which is the key behavioral signal for an upload action.

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

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

Purpose is front-loaded in the first sentence and every sentence carries distinct information (targeting, fixture generation, path policy, result reporting). The cost is density: several sentences cram three or four clauses each, so an agent must parse long chains to extract the acceptance-mismatch or credential-refusal rules.

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

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

For a 7-parameter, no-output-schema tool, this covers what an agent needs: how to target, how the file is sourced, what gets refused, and explicitly what the result contains (input named, delivery method, accept violation flag, cleared-input warning, request-fired status). Nothing essential is left to guesswork.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: fixture kind inference from the accept attribute (with pdf as the no-accept default), the purpose of `name` for boundary tests, and the exclusivity/fencing rules for filePath. It does not add anything about `task`, `session`, or the deprecated `objective`, which is why it falls short of a 5.

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

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

Opens with a specific verb and resource: 'Attach a file to an upload control the way a user does.' It immediately distinguishes itself from scout_click/scout_attach by explaining that the file chooser is intercepted rather than clicked, so an agent knows this is the file-specific path.

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?

Spells out three concrete targeting modes (visible input ref, chooser-opening control, omit ref for the only input) and their preconditions, plus the fixture vs filePath choice and the fallback ('if none did, click the form's submit, or check the next snapshot for a client-side rejection'). Alternatives are named rather than implied.

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

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

With no annotations, the description carries the burden and largely succeeds: it discloses the ordering guarantee (worst route first, grouped so a route is walked once) and the exact state effect of each verdict ('gone' resolves, 'present' stamps confirmed, 'changed' keeps open and says behaviour differs). Gaps remain around idempotency/overwriting an existing verdict and any permission requirements.

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

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

Front-loaded with the core action, then the no-argument worklist mode, then the verdict-recording mode. It is dense but every clause (ordering, grouping, evidence/repro, per-verdict semantics) carries information an agent needs; nothing is filler.

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

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

No output schema exists, and the description steps in to say what the worklist returns (findings with evidence and repro steps, in re-test order). For a 5-param read/write hybrid tool this is close to complete; the only shortfall is that the `session` parameter's concurrency semantics are never echoed outside the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add meaning for `verdict` (what each value does to the finding's lifecycle) and for `ids` (narrowing), which is above baseline, but `note` and `session` get no treatment in the description – the session concurrency guidance lives only in the schema.

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

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

States a specific verb+resource ('re-test findings earlier runs left open') and clearly separates its two modes: fetching the worklist vs. recording a verdict. It does not explicitly name any sibling (e.g. scout_resolve, scout_recheck_plan, scout_finding), so the agent must infer differentiation, but the scope is unmistakable.

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

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

Gives concrete timing guidance: 'after a fix wave, or at the start of a run against an app this project has tested before.' It also explains the ids-narrowing branch. What it lacks is an explicit when-not / named alternative (e.g. when to use scout_resolve instead of recording a verdict here).

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