Explore the layer tree

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

The annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial behavioral detail beyond that: results are flat rather than nested, order is document order, hierarchy is reconstructable via depth/parent, subtrees can be truncated, and outline mode changes both format and density. This is exactly the kind of non-obvious runtime behavior an agent needs.

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?

Every sentence in the description earns its place: the core action is front-loaded, followed by output structure, format trade-offs, and truncation handling. There is no filler or repetition, and despite its density it remains easy to scan.

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 six parameters and no output schema, the description provides a remarkably complete picture: what the response looks like, how to reconstruct hierarchy, how to detect/continue truncation, and when to switch formats. Parameter details like root default, file path, and types filtering are already fully covered by the input schema, so nothing important is missing.

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 the baseline is 3, but the description adds real value: it explains the default depth, the meaning of depth relative to the requested root, the purpose of children counts for deepening exploration, and the behavioral difference between json and outline formats. It also clarifies that cursor resumes a truncated traversal.

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 opens with a specific verb and resource: 'List the layers under a node', and immediately defines the tool's distinguishing behavior with breadth/depth limits. It also clarifies the output shape (flat list, document order) and the outline alternative, making it easy to tell apart from broader siblings like fig_overview or fig_find.

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 clearly states when to use the outline format ('4x denser for browsing') and how to continue truncated results via nextCursor. It does not explicitly contrast this tool with sibling tools such as fig_find or fig_node, but it gives enough contextual cues that an agent can infer the intended use case.

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