Skip to main content
Glama
software-mansion

Argent

Official
by software-mansion
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

debugger-component-tree

Fetch the on-screen component tree of a React Native app to locate UI elements and obtain normalized tap coordinates for automated interaction.

Instructions

Fetch the current screen of a running React Native app as a compact component text tree. Only shows on-screen components with unique positions — off-screen (scrolled) content, full-screen transparent wrappers, and implementation-detail components are pruned.

Each visible component is listed with its name, text content, and normalized tap coordinates in [0,1] space (fractions of the screen, not pixels — same space as tap/swipe/gesture). On an iOS simulator with a landscape UI (a rotated device, or an unfolded foldable), the tap coordinates are on the screen's axes, which the gesture tools use. When two or more devices share one Metro, pass the simulator's udid too. If the result says that the orientation could not be read, take tap coordinates from describe.

This is the preferred element discovery tool for React Native apps. More information in argent-react-native-app-workflow skill.

Workflow:

  1. Call this tool to get the component tree.

  2. Find the desired element by name, text, testID, or accessibilityLabel.

  3. Use the (tap: x,y) coordinates directly with the tap tool.

Call again after navigation or state changes since positions may shift. Set includeSkipped=true to see a summary of all filtered components. Use when you need tap coordinates for a React Native UI element. Returns a compact text tree with (tap: x,y) coords. Fails if Metro debugger is not connected.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
portNoMetro server port. Optional — omit it to use this device's port, 8081 by default. Ignored for Chromium, whose CDP port is encoded in device_id.
udidNoiOS simulator UDID from list-devices. Pass it when device_id is a logicalDeviceId (two or more devices share one Metro), so that the tap coordinates of a landscape UI are on the screen's axes. Give the UDID of the simulator that shows the app.
maxNodesNoMaximum total nodes to include. When exceeded, intermediate single-child wrapper chains are collapsed to preserve both root structure and leaf elements. Default: no limit.
device_idYesDevice id from list-devices — the SAME id you passed to debugger-connect (iOS simulator UDID or Android serial).
onScreenOnlyNoWhen true (default), only components visible on screen are returned. Set to false to include all mounted components including those scrolled off-screen. Useful when you need to understand the full page structure.
includeSkippedNoWhen true, appends a summary of all filtered components: total fiber count, JS-side skip counts by name, and TS-side filter pass removals. Useful for understanding what was pruned from the tree.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.27.0
    • changedInput schema / properties / udid / description
      Previous value: -"iOS simulator UDID from list-devices. Pass it when device_id is a logicalDeviceId (two or more devices share one Metro), so that the tap coordinates of a landscape UI are on the screen's axes."New value: +"iOS simulator UDID from list-devices. Pass it when device_id is a logicalDeviceId (two or more devices share one Metro), so that the tap coordinates of a landscape UI are on the screen's axes. Give the UDID of the simulator that shows the app."
  2. Changed1 schema field changedv0.26.0
    • addedInput schema / properties / udid
      Added value: +{
+  "description": "iOS simulator UDID from list-devices. Pass it when device_id is a logicalDeviceId (two or more devices share one Metro), so that the tap coordinates of a landscape UI are on the screen's axes.",
+  "type": "string"
+}
  3. Changed5 schema fields changedv0.25.0
    • removedInput schema / properties / port / default
      Removed value: -8081
    • changedInput schema / properties / port / description
      Previous value: -"Metro server port"New value: +"Metro server port. Optional — omit it to use this device's port, 8081 by default. Ignored for Chromium, whose CDP port is encoded in device_id."
    • addedInput schema / properties / port / maximum
      Added value: +65535
    • addedInput schema / properties / port / minimum
      Added value: +1
    • changedInput schema / properties / port / type
      Previous value: -"number"New value: +"integer"
  4. Changed1 schema field changedv0.17.0
    • changedInput schema / properties / device_id / description
      Previous value: -"Device logicalDeviceId from debugger-connect (iOS simulator UDID or Android logicalDeviceId)."New value: +"Device id from list-devices — the SAME id you passed to debugger-connect (iOS simulator UDID or Android serial)."
  5. First observedv0.15.0

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations the description carries the full burden and does well: it discloses the pruning rules (off-screen, full-screen transparent wrappers, implementation-detail components), the coordinate space, the landscape/multi-device Metro caveat, the staleness caveat (re-call after navigation), and the failure mode (Metro not connected). It does not describe pagination or rate behavior, but for a read-only introspection tool this is rich disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and pruning behavior, and the workflow is scannable. The closing lines ('Use when you need tap coordinates... Returns a compact text tree with (tap: x,y) coords. Fails if Metro debugger is not connected.') restate points already made earlier, so it is longer than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description fully specifies the return shape (per-component name, text, and tap coordinates in fractional screen space), how to consume it (feed coordinates to the tap tool), and the connection prerequisite. Nothing an agent needs to invoke and use it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all six parameters; baseline is 3. The description reinforces includeSkipped and udid semantics, but this is largely restating what the schema provides rather than adding new syntax or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (fetch the current screen as a compact component text tree) and immediately distinguishes the output format from siblings like describe or native-full-hierarchy by specifying on-screen-only pruning and normalized [0,1] coordinates. An agent can tell exactly what it gets back without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly declares itself 'the preferred element discovery tool for React Native apps' and provides a numbered workflow ending in the tap call. It also names an alternative path — take coordinates from describe when orientation could not be read — giving a real when-to-use-this-vs-that rule.

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

Deploy Server

Other Tools