pir_define_region

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.