app_read_window

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

With no annotations, the description carries the full disclosure burden and does a real job: it explains the visibility ceiling (TLabel text exists only as pixels), why that ceiling exists (no handle, no accessible object), and that WPF elements can be acted on via app_invoke_element. It does not state that the call is a pure read with no side effects, nor any auth/attach or timing 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?

The first line is a clean, front-loaded statement of purpose, but the middle is project history and rationale ('THE LAYER THAT WAS MISSING. This project read Altium three ways...') that is longer than the actionable content. The 'Returns' block restates the output schema verbatim, spending space on information the agent already has.

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?

Return shape is covered by the output schema and limitations are well explained, but for a zero-required-parameter, zero-schema-documentation tool the description leaves the two knobs unexplained and never says how to discover or target the window in the first place. An agent knows why it would call this, but not precisely how to parameterize it.

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 description says nothing about the two parameters. It never explains that dialog_title selects which window is read (or what the empty default means), nor what with_text controls despite the returned 'text' array being its obvious output — an agent must guess at both.

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 opening line gives a specific verb and resource ('Read a window through UI Automation') and the middle section makes concrete what it returns (elements with name/type/automation_id/enabled/rect and text). It differentiates itself from MSAA and OCR-based reading and from app_screenshot, but never mentions the plausibly similar sibling app_ui_snapshot or app_read_panel, so sibling differentiation is only partial.

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 states the decisive use case explicitly — Altium's WPF dialogs whose buttons are not child windows — and names the alternative with the condition that selects it ('Delphi's TLabel ... Use app_screenshot there'). What is missing is prerequisite context such as needing an attached session (app_attach) or how to pick a dialog among several open ones.

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