tool_capture_window

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 — and it goes far beyond basic mutation info. It discloses read-only status ('no input injection, no focus change'), explains the JPEG-vs-PNG size tradeoff relative to the 32 MiB provider cap, quantifies token costs (~12,500 vs ~50 tokens), and warns about the dpi_verified=false pairing hazard. This is exemplary behavioral transparency with zero annotation support.

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

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

The description is long but every clause earns its place — the coordinate alignment, file/scale/bounds return contract, size rationale, and token economics all carry operational value. It's front-loaded with the primary purpose and cropped-client-area detail. Slightly essay-like ('which is what keeps a long session's request body under the provider's 32 MiB cap') but purposeful; each sentence advances understanding.

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 tool with no annotations and zero schema coverage, this description is remarkably complete: it explains the return contract (bounds, scale, dpi_verified) even though an output schema exists, covers file-saving semantics, and anticipates the exact failure mode an agent would hit (huge base64 payloads). Nothing critical an agent needs to invoke it correctly or interpret its output 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 description coverage is 0%, so the description must compensate — and it does, covering nearly every parameter in prose: hwnd/title (provide either), client_only (client area cropping), max_dim (downscaling), quality (JPEG q80 default), include_data_uri (token cost and base64 inlining), and save_path (read with read_image). A minor gap is that image_format is never explicitly named, and some parameters aren't labeled by their schema property names, but the intent is conveyed 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?

States a specific verb and resource ('Capture a window screenshot and SAVE IT TO A FILE') and adds a distinguishing detail — cropping to the client area with aligned coordinate systems — that differentiates it from siblings like tool_skyshot. The purpose is unambiguous and the resource (window) is 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?

Gives explicit input guidance ('Provide hwnd or title substring') and a conditional rule for when to pass include_data_uri ('only when a caller genuinely cannot read a file'), plus a recommended alternative (read_image). However, it never names sibling tools as explicit exclusions (e.g., when to prefer tool_skyshot or tool_get_window_rect over this), so it lacks direct when-not guidance.

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