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 return format, the coordinate system (display-coordinates, not image pixels), and a security caveat about prompt-injection content in OCR output — a real, non-obvious behavioral risk. It omits OCR latency/cost and whether the call is side-effect-free, which is why it falls short of 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 sentences, front-loaded with the core action, then chaining guidance, then the warning — each sentence earns its place with no repetition of schema content.

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

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

There is no output schema, but the description compensates by describing the returned 'matching lines with display-coordinate bounding boxes' and how to consume them, and it flags the untrusted-content risk. Coverage is solid for a read-only lookup tool; only cost/permission behavior is left implicit.

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

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

Schema description coverage is 100%, so every parameter (query, region, displayId, maxMatches, caseSensitive) is already documented including defaults and bounds. The description adds no parameter-level meaning beyond what the schema states, 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 (search) and resource (screen region) with the mechanism (OCR) and return shape (matching lines with bounding boxes). It also distinguishes itself from siblings by naming the downstream consumer, `screenshot_region`, which no screenshot/read_screen_text tool would do.

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 three concrete example intents ('find the error message', 'where is the submit button') and an explicit follow-up action. It stops short of stating when NOT to use it versus `read_screen_text` or `screenshot`, but the triggering context is clear.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the return shape (diagnostics, no image), the baseline caching side effect, the read-only default (updateBaseline=false), and the first-observation baseline rule. It lacks detail on the distance scale/threshold semantics an agent would need to act on the number.

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

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

Three tight sentences, front-loaded with the core action and immediately followed by the output nature, usage rationale, and default. 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 3-param, read-only compute tool with no output schema, the description explains the return nature and baseline behavior adequately. It stops just short of interpreting what the returned distance value means for decision-making.

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 cacheKey, displayId, and updateBaseline are already well documented in the schema (including the default-false meaning). The description only restates the default value, adding little beyond 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 (compute the perceptual-hash distance) and resource (current screen vs cached baseline), and distinguishes itself from siblings by noting it 'Returns only diagnostics — no image' and shares state with screenshot_if_changed. An agent can tell it apart from screenshot/wait_for_change without opening schemas.

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

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

Gives a clear context — 'Useful for polling whether a screen has changed before spending vision tokens' — and notes the read-only default. It does not explicitly exclude or route to alternatives like wait_for_change, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full disclosure burden. It reveals the return payload shape (id, name, primary flag), which is genuine added value, but says nothing about whether the display list can change at runtime, whether enumeration requires any permission, or how refreshes are handled. Adequate for a trivial read, but incomplete for a zero-annotation tool.

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

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

Two sentences, no filler, with the resource and return fields front-loaded and the follow-up instruction second. Every clause earns its place.

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

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

There is no output schema, so the description must describe returns — it does so at a field level (id, name, primary flag), which is sufficient for a simple enumeration call. Only the absence of any note about dynamic display changes or permissions keeps it from being fully complete.

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

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

The tool takes no parameters, so per the baseline a 4 applies. The description correctly adds no per-argument detail because there are none to document.

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

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

Specific verb (List) plus resource (connected displays) with the returned fields enumerated (id, name, primary flag). It is immediately distinguishable from siblings like list_windows or screenshot, which deal with windows or pixels rather than display enumeration.

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 states the downstream use case: take the returned id and pass it to `screenshot` or `screenshot_region` to target a monitor. That names the alternatives and the condition that selects them, but there is no guidance on when this call is unnecessary (e.g., single-monitor setups) or any prerequisites.

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. It usefully defines scope ('visible top-level windows') and the returned fields, but is silent on ordering, whether minimized/child/elevated windows appear, 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?

Two tight sentences: the core behavior and return fields come first, the usage hint second. No redundant restatement of the name or title, and nothing padded.

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

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

With no output schema, the description compensates by naming the returned fields, and it covers the use case and scope. Remaining gaps (result ordering, edge-case window states) are minor for a simple read-only enumerator.

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

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

Schema description coverage is 100%, so the single 'filter' parameter (case-insensitive substring on title, max 200 chars) is already fully documented. The description adds nothing about filtering, 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?

Specific verb (List) + resource (visible top-level windows) plus the exact fields returned (handle, title, process id) and the scope qualifier 'visible top-level'. An agent can distinguish this enumeration tool from the screenshot/OCR-oriented siblings 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 a concrete usage context: 'orienting yourself before deciding what to screenshot', which implicitly routes the agent to this tool ahead of the screenshot family. It does not explicitly name a sibling or state when not to use it, so it stops short 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 full behavioral burden and does disclose several real traits: the token-cost profile (~10-100x fewer tokens than vision), the performance penalty of omitting region, and a security warning that OCR text is untrusted and may contain attacker-crafted prompt-injection content. It does not mention OS-level screen-recording permission requirements or failure behavior, which are the remaining gaps.

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

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

Three tight sentences: purpose and cost trade-off first, then the opt-in flag, then the security warning. No filler, nothing repeated, and the most decision-relevant information is front-loaded.

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

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

No output schema exists, and the description does describe the return shape (recognized text, optionally per-line bounding boxes with confidence in display coordinates). Missing only secondary operational details such as permission prerequisites and what happens on an empty/failed OCR pass.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing the text-only default as a token-saving choice and by stating that line boxes are meant for 'follow-up region capture' (linking to screenshot_region), plus the maxLines default is documented in the schema itself.

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+resource (run OCR on the screen or a region and return recognized text) and explicitly contrasts itself with the `screenshot` sibling on cost, 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?

Gives a clear selection rule ('cheaper than screenshot when you only need text') and explains when to enable includeLineBoxes (follow-up region capture). It never mentions the closely related `find_text_on_screen` sibling, which an agent might otherwise confuse with a text search on screen, so it stops short of full alternative coverage.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses blocking behavior ('the entire window blocks before any frame is returned', 'NOT a real-time stream'), the dedup/selection rule (dHash distance, first+last always kept), and hard caps (60s, 12 frames). This is exactly the behavioral context 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-loaded with the core action, then progressively adds behavior, caps, and routing. Dense but every clause carries signal; the only minor cost is that the caps and the alternative-tool guidance could sit closer to the top.

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 correctly explains the return value shape (first + last + middle keyframes) and the blocking semantics. Combined with a fully documented schema, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that targetFps is capped at 5 because dHash discards near-identical frames, and reiterates the maxFrames selection policy. It does not cover format/quality/maxEdge rationale in the description, though the schema handles those.

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

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

States a specific verb+resource (capture screen, return keyframes) with scope and mechanism (deduplicated by perceptual hash). The final sentence explicitly contrasts with the sibling `wait_for_change`, so an agent can distinguish it without opening schemas.

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

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

Gives an explicit use case ('show me what happened in the last 10 seconds') and names the alternative tool plus the condition that selects it ('tell me when something changes' → wait_for_change). Exclusions and context are both stated.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the auto-resize default (maxEdge=1600) and the vision-token rationale, plus the return type. It omits real operational traits such as OS screen-recording permission requirements and what happens with occluded or off-screen windows.

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

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

Three tight sentences: what it does, when to use it, then a cost-related default. Purpose is front-loaded and every sentence earns its place.

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

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

For a zero-required-param, single-purpose capture tool with a 100%-documented schema, the description covers purpose, trigger, and the key cost tradeoff; the returned image type is stated so no output schema is needed. It falls just short on permission/OS prerequisites that an agent may need before calling.

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 format, maxEdge, quality, and displayId are already fully documented in the schema, including defaults and ranges. The description's mention of maxEdge=1600 only repeats what the schema default already states, adding no new semantic 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?

States a specific verb+resource ('Capture the entire primary display... return it as an image') and defines scope as the whole display, which implicitly separates it from the sibling screenshot_region. An agent can tell what this returns without opening the schema.

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

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

Gives clear when-to-use triggers ('when the user asks you to see, look at, describe, or troubleshoot what's on their screen'). However, it never names the alternative siblings (screenshot_region, screenshot_if_changed, get_screen_diff) or states when NOT to use this, leaving sibling routing to inference.

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

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

No annotations are provided, so the description carries full burden. It discloses key behaviors: conditional return, no image on unchanged, zero vision tokens, first-call baseline establishment, and pinBaseline semantics. It does not mention authentication or rate limits, but those are typically handled elsewhere. The dHash distance and threshold calibration are explained in the schema, not repeated 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?

Three sentences, front-loaded with the core distinction, then economic benefit, then edge cases like first call and pinBaseline. No waste; every clause adds decision-relevant information.

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

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

For a 7-parameter tool with no output schema and no annotations, the description is remarkably complete: it covers the conditional logic, token cost implications, baseline establishment, and pinning. It does not explain return structure (e.g., diagnostics), but that is not critical for invocation. All key behavioral aspects are addressed.

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 fully documents all 7 parameters. The description adds contextual meaning to threshold via the dHash distance reference and pinBaseline behavior (keep reference point fixed), which supplements the schema's threshold calibration examples. Baseline 3 is for high coverage, but the description adds value by explaining the trade-offs and default behaviors conceptually.

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 precise verb+resource+condition: capture the screen only if a perceptual-hash change exceeds the threshold. It clearly distinguishes itself from the plain 'screenshot' sibling by adding conditional capture, and from 'get_screen_diff'/'wait_for_change' by returning an image versus diff metadata.

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 use case (polling / 24h monitoring) and the economic rationale (static screens cost 0 image tokens). It describes when the first call returns an image (reason=no_baseline) and the purpose of pinBaseline for fixed reference comparisons, giving clear when-to-use guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the token-cost advantage, which is a useful trait, but says nothing about coordinate origin, multi-monitor/displayId behavior, resize defaults, or error conditions for out-of-bounds regions. For an 8-param capture tool with zero annotation coverage, this is a substantial gap.

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

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

Two sentences, front-loaded with the core action, then the usage/benefit rationale. 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?

Purpose, usage, and cost rationale are covered, but with no annotations and no output schema, the description should do more to disclose coordinate semantics, display targeting, and failure modes. Adequate but with clear gaps for a capture operation.

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

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

Schema description coverage is 100%, so all 8 parameters (including maxEdge default, format enum, and displayId pattern) are already documented in the schema. Baseline 3 applies; the description adds no parameter-level detail beyond the schema.

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

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

States a specific verb and resource ('Capture a rectangular region of the screen') that is precisely distinguishable from the sibling 'screenshot' and from screen-reading tools. An agent can immediately tell this is the region-scoped variant.

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 when-to-use condition ('user points at a specific area or you only need part of the screen') and contrasts with the full-screen alternative implicitly via 'way cheaper than a full screenshot'. It does not name the sibling tool `screenshot` explicitly, so routing is strong but not fully prescribed.

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 full behavioral burden. It discloses the blocking behavior ('long-blocks the MCP transport — keep ≤ 5 min'), the 5-minute hard timeout cap, the CPU cost profile, and — critically — the two distinct return shapes (image on change, no-image diagnostics on timeout). It doesn't mention permission or error mode requirements, but the operational semantics are unusually well surfaced.

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

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

Five sentences, each earning its place: behavior, use-case motivation, return shapes, cost profile, and hard cap. Front-loaded with the core action. No filler or repetition.

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

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

For an 8-param long-polling tool with no output schema and no annotations, the description covers the essential behavioral envelope (blocking, timeout cap, return shapes, cost). It would be stronger still with a note on permission/auth needs or error behavior, but the operationally risky aspects are 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 description coverage is 100%, and the schema already documents caching, threshold semantics, polling, and default values in detail. The description largely restates what the schema covers (perceptual-hash distance, dHash downscale, timeout cap). Baseline 3 applies since the schema does the heavy lifting for parameter meaning.

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

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

States a specific verb and resource ('Long-poll the screen and return as soon as the perceptual-hash distance from the start frame ≥ threshold') with clear semantics. The 'ping me when X finishes' framing and the contrast with screenshot_if_changed/get_screen_diff make it distinguishable from siblings. No ambiguity about what the tool 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?

Explains the intended scenario ('ping me when X finishes' workflows) and states that the server does the polling so the client only spends a turn on change. However, it does not explicitly name sibling tools like screenshot_if_changed or get_screen_diff as alternatives or draw when-not-to-use boundaries, leaving sibling routing to inference.

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