native-full-hierarchy

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

With no annotations, the description carries full responsibility for behavioral disclosure, and it does so thoroughly. It warns about extremely large output (100KB–500KB+), lists statuses (restart_required, service_stale, connect_pending, init_failed) with exact recovery actions, and clarifies that non-connected apps return statuses rather than failures. This goes far beyond the schema's static parameter descriptions.

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?

Though long, every section earns its place: warning first, then alternatives, parameter tuning advice, and careful status handling. The structure is front-loaded with the most critical information, and the status guidance is exhaustive enough to prevent dangerous retry loops.

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 tool has no output schema and no annotations, the description is remarkably complete. It covers expected return shape, failure modes, status-value semantics, terminal cases, and advice about scaling output. An agent can invoke this tool correctly and know what to do after almost every possible result.

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%, and the description adds meaningful guidance on top: skipClasses/skipClassPrefixes examples, a concrete SwiftUI prefix value, a warning against broad prefixes like '_UI', a default for maxDepth, and a recommendation to use the fields parameter to limit output. This materially helps an agent pick and fill the right parameters.

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 first sentence states a specific verb and resource: 'Get the complete UIKit view tree for the running app.' It also distinguishes itself from the sibling tool by saying 'Prefer native-find-views for targeted queries' and notes when this tool is useful (deep layout debugging, accessibility label checks). This is unambiguous and avoids confusion with siblings.

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 explicitly tells the agent when to use this tool versus native-find-views and gives concrete use cases: 'deep layout debugging, finding views with no accessibility labels, or verifying view structure not exposed through the accessibility tree.' It also explains when not to retry, including terminal conditions for Apple system apps and specific instructions for each status code.

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