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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does so effectively: it details the global coordinate system and negative x on multi-monitor layouts, explains that masks are ignored regions-local rects, and discloses that redefining a name replaces the old region and discards its last sample—a significant side effect. It does not mention return values or errors, but for a definition tool the described behaviors are quite transparent.

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

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

The description is three short sentences with no filler. The main purpose is front-loaded in the first sentence, followed by essential coordinate clarification and mask/redefinition behavior. Every sentence delivers necessary information that a caller would need, and the structure is easy to scan.

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

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

The tool has 6 parameters, no output schema, and no annotations, so the description carries significant weight. It explains the coordinate system, masks, and redefinition side effects, but it omits any mention of what the tool returns (e.g., success/failure, region handle) or any error conditions. Given the absence of an output schema, this leaves a gap in fully understanding the call contract. The description covers usage well but falls short of being completely context-rich.

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 input schema has only terse descriptions for x/y/w/h ('left edge, pixels'), and no descriptions for name or masks. The tool description compensates by explaining the coordinate frame (global layout, negative x on wlroots multi-monitor) and that masks are area-local and ignored—meaning that the description adds crucial semantic value for coordinate interpretation and mask usage that the schema lacks. Given the 67% schema coverage, the description lifts the parameters to a functional understanding.

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

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

The description opens with 'Name a rectangle of the screen to watch', a precise verb-noun-resource statement that immediately distinguishes this tool from siblings like pir_define_window and pir_pick_region. It clearly identifies the action (defining a region) and the object (a named rectangle to monitor). The mention of masks and redefinition further clarifies its role without any ambiguity.

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 conveys exactly what the tool does and provides useful context about when to use it (for defining a rectangle to watch) and how masks work. It does not explicitly point to alternative tools or state when not to use it, but the presence of pir_define_window and pir_pick_region in the sibling list makes the intended usage clear. Since there are no exclusions or alternatives mentioned, it falls between implied usage and clear context with no exclusions, earning a 4.

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 of behavioral disclosure. It reveals several important behaviors beyond the schema: window geometry is re-looked-up per capture, resizes count as maximal change, masks are window-local, and the accepted id formats are described. This is substantial and genuinely helpful.

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 with no filler. The core behavioral distinction is front-loaded, and the id-format detail is placed at the end as useful supplementary information. 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?

Given no annotations and no output schema, the description does a good job covering the key behavior and the window-id formats. Minor gaps remain: the `name` parameter is not defined, and mask coordinate semantics could be more explicit. These are inferable but not fully spelled 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 description coverage is 0%, so the description must compensate. It does explain the meaning of `window` well and adds that masks are window-local. However, the required `name` parameter is left unexplained, and the exact coordinate system of the masks (origin relative to window) is only implied by 'window-local'. Partial compensation, not 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 begins with a specific verb and resource: 'Watch a window rather than a fixed rectangle.' It clearly states that geometry is looked up from the window id before every capture, and it explicitly contrasts this with fixed rectangles, distinguishing it from the sibling pir_define_region.

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

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

The description gives clear context for when to use the tool: when the region should follow a moving window rather than stay fixed. It also explains what window identifiers are accepted. It does not explicitly name sibling alternatives or state when not to use it, but the contrast with 'fixed rectangle' implies the boundary adequately.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It communicates what data is included (geometry and masks) and implies a non-mutating list operation, but it does not state side-effect-free behavior, return format, or whether the list is live/snapshot. This is adequate but not rich, matching the 'minimal viable' level.

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 concise sentence with no filler. It front-loads the core subject ('regions currently defined') and appends the relevant detail about geometry and masks 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 simple zero-parameter listing tool, the description is nearly complete: it states the resource and the included contents. It does not specify the exact return structure or mask representation, but the absence of params and output schema keeps the complexity low enough that this is only a minor gap.

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

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

The tool has zero parameters, so the input schema is inherently complete and there is little for the description to add. The baseline of 4 applies because no parameter documentation burden exists.

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

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

The description clearly identifies the resource (currently defined regions) and the information returned (geometry and masks), making the tool's purpose understandable. The tool name supplies the 'list' verb, and the resource differentiates it from sibling actions like define_region, remove_region, and pick_region. It stops short of a 5 because the description itself is a noun phrase rather than an explicit action statement.

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

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

No explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives mentioned. However, the read-only listing nature is implied by 'currently defined,' which makes it reasonable for an agent to use this when it needs an overview of existing regions. This qualifies as implied usage rather than fully absent 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 provided, the description carries the full burden. It discloses two important behavioral traits: the operation is interactive ('Ask the person') and it invalidates the region's last sample, explaining why masked grids are not comparable. This is meaningful side-effect disclosure, though it does not mention irreversibility or whether an existing mask is replaced.

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 concise sentences with no filler. The primary action is front-loaded, the use-case examples are compact, and the side effect is explained in a single, purposeful second sentence. Every part adds 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?

For a single-parameter tool, the description covers the action, the interactive nature, the target scenario, and a key side effect. However, it lacks explicit parameter-to-region mapping and does not describe what happens after drawing or what the tool returns, leaving some operational ambiguity.

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

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

The schema has one required string parameter, `name`, with no description coverage. The description says 'inside an existing region' but never states that `name` must identify that region, nor does it clarify what value to pass. The parameter semantics are therefore left mostly to inference.

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

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

The description clearly communicates an action: ask the person to draw a rectangle inside an existing region so that part is ignored. The examples (clock, spinner, caret) and the mention of 'masked grids' make the mask-specific purpose clear and distinguish it from the sibling sampling/region tools.

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

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

The description implies the tool should be used when an existing region contains a distracting element, and it explicitly requires the region to already exist. However, it does not name alternatives or state when not to use this tool, so the guidance is mostly 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool blocks until completion or timeout, can be cancelled with Escape, and returns the geometry. It doesn't mention whether the picked region is stored for later use, but the core interactive and blocking traits are clear.

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

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

Three sentences, no filler, with the core behavior front-loaded and the usage guidance and blocking behavior included. 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?

The description is largely sufficient for knowing what the tool does and how it behaves, but it omits what 'name' is for, which is a required parameter. Without annotations or an output schema, that gap keeps the definition at minimum viable rather than fully complete.

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

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

Schema coverage is only 50%: the required 'name' parameter has no schema description and the tool description does not clarify it. The optional 'purpose' is documented in the schema, but the description adds no meaning for the parameters, so it fails to compensate for the uncovered one.

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

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

The description clearly states a specific action: ask the person at the screen to draw a rectangle to watch. It distinguishes itself from pir_define_region by explaining the human-in-the-loop interaction and explicitly calling out that alternative.

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

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

The description gives an explicit usage rule: prefer this over pir_define_region whenever a human is present. It also explains the UX outcome and blocking behavior, so an agent knows when this tool is the right choice.

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

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

With no annotations, the description carries the behavioral burden. It discloses the interactive prompt, the box overlay, Escape cancellation, and the follow behavior. It stops short of stating whether an existing region of the same name is overwritten or what the cancellation return looks like, but the core interaction is transparent.

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

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

Two sentences, front-loaded with the core user interaction, with no wasted or redundant wording. It adds essential behavioral detail without restating the tool name or schema.

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

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

For a human-in-the-loop picker, the description covers what the user sees, how to cancel, what happens after selection, and when to prefer it over the main sibling. It is slightly incomplete only in not describing return/cancel semantics or the required name parameter's role.

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 only 50% because the required 'name' property lacks a description. The tool description adds operational context but does not explicitly explain how 'name' maps to the region that follows the window, leaving that inference to the agent. The 'purpose' parameter is already handled by the schema description.

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

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

The description names a specific action ('Ask the person at the screen to click the window to watch'), the interaction mode (visible windows offered as boxes), and the outcome (the region follows that window). This clearly identifies the tool as a human-driven window picker and distinguishes it from region- or mask-based siblings.

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

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

It explicitly states 'Prefer this over pir_define_window when a human is present,' giving a concrete routing condition and naming the alternative. This is sufficient for an agent to select this tool over the most similar sibling without opening another schema.

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 present, so the description carries the full burden. It only says 'Forget a region,' implying deletion, but discloses nothing about whether the action is irreversible, whether it cascades to dependent entities (e.g., windows or masks that reference the region), whether it errors on nonexistent names, or any side effects. This is a significant gap for a mutation operation.

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

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

The description is a single short sentence, which is concise, but it is overly minimal. It front-loads the core action but lacks necessary elaboration. The brevity is not harmful, but it fails to provide sufficient detail for correct usage.

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 simplicity (one param, no output schema), the description could be sufficient if it addressed key behaviors. However, it omits crucial context such as error handling, irreversibility, and effects on related resources. The sibling tools suggest regions are used in workflows (e.g., picking, defining), so removal likely has implications that are not disclosed.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain the 'name' parameter beyond implying it identifies a region. While the parameter name is self-explanatory, there is no information about format, case sensitivity, or whether it must match an existing defined region exactly. The description adds no value beyond 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?

The description states a clear verb ('Forget') and resource ('region'), indicating removal. It differentiates from sibling tools like define_region (creation) and list_regions (retrieval) at a basic level. However, it does not elaborate on what 'region' specifically refers to in context, but the tool name and siblings make it reasonably clear.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., region must exist), nor does it contrast with siblings like pir_define_region or pir_pick_region. The usage context is implied by the name but not explicitly 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?

The description discloses important behavior: null on first call, cheap, and non-blocking. With no annotations provided, the description carries the behavioral burden. It does not mention that each call updates the stored baseline sample (a side effect), nor does it describe the return value/score format. This is useful but incomplete.

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

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

Two sentences with zero filler. The core function is front-loaded, followed by practical use cases. 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?

The core function and use cases are clear, but significant gaps remain: the 'name' parameter is undocumented, the meaning of 'score' is vague, there is no output schema, and the side effect of updating the baseline is omitted. An agent cannot fully determine how to call this correctly or interpret the result.

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

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

Schema description coverage is 0%, and the sole parameter 'name' is never explained in the description. There is no statement that 'name' identifies a previously defined region, nor any format guidance. The description refers to 'the region' but never links it to the input parameter, leaving the agent to guess its meaning.

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

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

The description states a specific verb and resource: 'Capture the region once and score it against the previous sample of the same region.' It also clarifies the first-call behavior (null) and distinguishes itself from blocking siblings by emphasizing it is 'non-blocking.' An agent can understand exactly what this tool does and how it differs from waiting or defining operations.

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?

Three concrete use cases are spelled out: check the capture command works, take a baseline, and ask 'did anything happen there since I last looked?'. These give clear context for when to invoke this tool. However, it does not explicitly name alternative tools or state when not to use it beyond implying that blocking waits are different.

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 so well: it discloses blocking semantics, timeout behavior, and both return outcomes. It does not discuss side effects or prerequisites like having the region already defined, but as a read/observe tool those are less critical.

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 plus examples carry the core definition, return behavior, and use cases with no fluff. The mechanism is front-loaded and the examples are concrete rather than filler.

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

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

For a blocking wait tool with no output schema and no annotations, the description covers the essential return values, timeout, and representative use cases. It could be more complete by stating that the region must already exist or be defined, but the core agent-facing contract is adequately specified.

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 high (80%), so the baseline is 3; the description adds little parameter-level detail beyond what the schema already provides. The one uncovered parameter, name, is not described in either place, and the description doesn't help resolve the schema's contradictory timeout max (540000 in text vs 9007199254740991 in maximum).

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 behavior: block until the region changes from its starting state or until timeout_ms. It also defines the return contract (changed=true with score, changed=false with largest score), which makes the tool's purpose unmistakable and differentiable from wait_for_stillness.

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 'doorbell' framing plus concrete examples (build output moves, dialog closes, game loads) gives the agent clear when-to-use guidance. It doesn't explicitly mention when not to use it or name wait_for_stillness as the inverse alternative, 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 burden of behavioral disclosure, and it does so well: it explains blocking, the condition for success, timeout behavior, and the 'still=true' alarm state. It does not describe the full return shape or whether the operation is read-only, but the core behavior is transparent.

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

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

The description is two tight sentences with no filler. The primary behavior is front-loaded, and the second sentence adds valuable interpretive guidance about short versus long windows.

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 core semantics are covered, but with no output schema and six parameters, the description leaves gaps: the meaning of 'name' is unclear, and the exact return value on timeout versus success is only hinted at through 'still=true'. It is adequate but not 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 input schema covers 5 of 6 parameters with descriptions, so the baseline is 3. The tool description adds little parameter-specific meaning beyond referencing threshold and still_for_ms; notably, the required 'name' parameter is left undocumented in both the schema and description.

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

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

The description states a specific behavior: block until consecutive samples stay below threshold for still_for_ms or timeout_ms. It clearly identifies the tool as a stillness/change-frozen detector, though it does not explicitly contrast itself with the sibling pir_wait_for_change.

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

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

The description gives practical guidance: a short window means the page has settled and is safe to act, while a long window on something that should keep changing indicates frozen content. It does not explicitly mention alternatives or provide exclusions, but the intended use cases are clear.

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