app_screenshot

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 non-obvious behaviour: it writes a file to disk (defaulting to the workspace directory), returns a JSON envelope with path and hwnd, and the agent must then read the file to actually see anything. It does not cover capture limits such as window size, off-screen or minimised windows, or multi-monitor behaviour, which are the obvious failure modes for a screenshot 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?

The opening sentence and the Args/Returns block are front-loaded and efficient. The middle paragraph, however, is a developer-facing rationale about ui/ocr.py and the history of the tool — it justifies the tool's existence to a human reviewer rather than helping an agent decide or call it, and it inflates the definition considerably.

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-parameter, zero-required capture tool this is close to complete: destination, dialog targeting, return shape, and the crucial 'read the file afterwards' step are all stated. Since an output schema exists, the Returns block is partly redundant, but the pointer to read the PNG is real added value. Missing only edge-case behaviour for unusual windows.

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 entirely, and it does: path is explained as the PNG destination with the workspace-directory default and the reason for it, and dialog_title is explained as selecting a dialog instead of the main window. Both of the two optional parameters gain meaning the bare schema does not provide.

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 first line gives a specific verb and resource: capture the Altium window, or a single dialog, into a PNG file. That is clearly distinguishable from neighbouring tools such as app_read_window and app_ui_snapshot, since the output is an image rather than a text tree, though the description never names those siblings explicitly. The purpose is unambiguous but the differentiation is implied rather than stated.

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 a concrete usage rationale: use it when judgements must come from what is drawn on screen rather than from an accessibility tree that omits rendered elements — greyed controls, rendered dialog text, which page is in front. It does not name alternatives or state when not to use it, so an agent must infer that app_read_window/app_ui_snapshot remain the cheaper first choice for tree-visible content.

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