ai_debug_screen

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

The description discloses that it reports findings and optionally attempts recovery when auto_fix=true, which is useful transparency. However, it does not explain what recovery actions may be taken, whether they can modify app state, or what the default read-only behavior entails, leaving side effects partially unspecified.

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 compact and well-structured, using two sentences to cover purpose, output, optional behavior, and a prerequisite. Every sentence contributes useful information with no redundant or vague filler.

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?

Given the simple parameter list and no output schema, the description covers the tool's purpose, optional configuration, and prerequisite. 'Report findings' is somewhat vague about the exact output format, and 'attempts recovery' lacks detail, but the overall context is sufficient for basic invocation.

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?

The only parameter, auto_fix, has schema title and default but no schema description. The tool description supplies meaning by stating that auto_fix=true enables recovery attempts, effectively covering the parameter's role. It could be more explicit about the default false behavior, but the semantic gap is mostly filled.

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 ('diagnose'), a clear resource ('current screen'), and specific conditions being detected (crashes, ANRs, permission blockers, unexpected overlays), followed by reporting findings. This clearly distinguishes it from sibling tools like ai_understand_screen or find_element.

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 prerequisite (requires OPENAI_API_KEY or LLM_* env) and behavior for auto_fix=true, but provides no explicit guidance on when to choose this tool over related siblings such as ai_understand_screen or ai_execute_goal. It lacks when-to-use and when-not-to-use direction.

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