glass_start

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

Adds behavioral context beyond annotations: explains that a11y is on by default, that passing false skips the accessibility bus for canvas apps, and that window_hint handles multi-window or handoff cases. This supplements the sparse annotations (readOnlyHint=false, destructiveHint=false) with useful details about defaults and side effects.

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 four sentences, front-loaded with the core purpose, and each sentence adds distinct value (backend, a11y, window_hint) without fluff or repetition. Every sentence earns its place.

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 tool with 9 parameters and a nested object, the description covers the most critical aspects (purpose, backend, a11y, window_hint) while leaving parameter details to the schema. It doesn't explicitly mention return format beyond 'window geometry' (no output schema), but that is adequate for the complexity. Minor gap: it doesn't summarize the env behavior on android or the timeout, but these are clearly documented in the schema.

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?

With 100% schema coverage, the baseline is 3, but the description adds value: it explains the backend default, gives a pragmatic reason for a11y:false (canvas/pixel-only apps), and clarifies window_hint's purpose. This goes beyond simply repeating schema descriptions.

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 states a specific verb+resource: 'Build, launch, and locate a native GUI app; returns its window geometry.' This clearly distinguishes it from sibling tools like glass_list_windows (which lists windows) and glass_select_window (which selects), making the tool's purpose unambiguous.

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?

Provides clear usage context: how to choose a backend, when to pass a11y:false, and how to use window_hint for disambiguation. However, it does not explicitly mention alternatives like 'use glass_list_windows if you just need to list windows,' so it lacks explicit exclusions, but the purpose is distinct enough that context is clear.

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