Observe Studio

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

Annotations already mark it read-only and non-destructive, and the description adds non-obvious behavior: persisted preferences, include_text=auto resetting UIA, and separate observation clearing screenshot-typing focus. It does not fully explain return contents, but it meaningfully extends the annotation profile without contradicting it.

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 very compact and mostly front-loaded, with defaults clustered and no filler. The telegraphic fragments, especially "Fresh Studio image/token," reduce clarity but do not add wasted text.

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 observation tool with eight optional parameters and no output schema, the description should define what "token" contains and what is returned. It gives coordinate conventions and defaults but leaves return shape and several controls unclear.

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 50%, and the description supplies several defaults (JPEG 1600/q85, compact output, native-dialog UIA) plus the include_text=auto reset behavior. It still omits settle_ms, max_elements, and include_screenshot, so it only partially compensates for the remaining schema gaps.

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 "Fresh Studio image/token" only implies that it obtains a fresh screenshot and UI token; it never states a clear verb or that it captures the Studio UI tree. Coordinate-system and default notes help identify it as an observation tool, but the purpose is still vague relative to siblings like studio_status or studio_capabilities.

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?

There is no statement of when this should be used instead of studio_status, studio_list_windows, or studio_capabilities, and no prerequisites are given. The only guidance is coordinate handling and the focus-clearing caveat, which is not tool-selection guidance.

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