native-user-interactable-view-at-point

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

With no annotations, the description fully carries the transparency burden and does so thoroughly. It discloses return shape, null behavior, ancestor/subview defaults, raw coordinate semantics, all special statuses with concrete recovery steps (restart app, restart tool-server, wait), and failure cases such as Apple system apps being rejected outright.

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 longer than average but every sentence earns its place: purpose, comparison, use cases, return contract, coordinate warning, and detailed status handling. It is front-loaded with the core purpose and then moves into operational details, though the status block is dense and could be tightened.

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?

This is a complex 10-parameter tool with no output schema and no annotations. The description fully compensates by covering return values, coordinate semantics, defaults, status codes, recovery actions, and error boundaries. An agent has enough information to select, invoke, and interpret results correctly without guessing.

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 100%, so baseline is 3. The description adds real value beyond the schema by explaining that x and y are raw iOS window coordinates NOT normalized [0,1] tap coordinates, and by clarifying default behaviors for ancestors and subviews that affect includeAncestors/includeChildren interpretation.

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 action: inspecting the deepest UIView at a raw native window point that would actually receive touch input. It explicitly distinguishes itself from the sibling native-view-at-point by noting it respects userInteractionEnabled and follows UIKit hit-testing semantics.

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?

Gives clear when-to-use guidance: 'Use when a tap lands somewhere unexpected or does nothing' and names the sibling alternative native-view-at-point as a contrast point. It also provides explicit do-not-retry/restart guidance for error statuses, which helps the agent decide whether to invoke or recover.

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