Skip to main content
Glama
software-mansion

Argent

Official
by software-mansion
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

debugger-component-tree

Get tap coordinates for React Native UI elements by fetching the on-screen component tree, with normalized coordinates for direct use in tap gestures. Prunes off-screen and wrapper components to show only actionable elements.

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.
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.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"
+}
  2. 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"
  3. 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)."
  4. First observedv0.15.0

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and meets it well. It discloses pruning of off-screen components and wrappers, normalized [0,1] tap coordinates, orientation-axis handling, the need to pass udid for shared Metro setups, and the failure condition when Metro is not connected.

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?

The description is longer than average but well-structured with a workflow and dense, useful detail. The final sentence repeats the 'compact text tree with tap coords' idea already in the opener, which is the only real redundancy. Overall it earns its length for a complex tool.

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?

There is no output schema and no annotations, so the description fully compensates by explaining what the tool returns, the coordinate space, when to re-call, how to surface skipped components, and when it fails. It also provides a concrete 3-step workflow, making the tool safely invocable by an agent.

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 description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds contextual color around udid and includeSkipped, but mostly repeats what the parameter descriptions already say. This is the baseline 3 case where the schema does the heavy lifting.

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?

The description states a specific verb and resource: 'Fetch the current screen of a running React Native app as a compact component text tree.' It also positions itself explicitly as 'the preferred element discovery tool for React Native apps', which distinguishes it from sibling debugger/native-hierarchy tools.

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

Usage Guidelines4/5

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

The description gives clear when-to-use guidance ('Use when you need tap coordinates for a React Native UI element'), a numbered workflow, and a prerequisite/limitation ('Fails if Metro debugger is not connected'). It also advises re-calling after navigation or state changes. However, it does not explicitly say when to prefer sibling tools like native-describe-screen or native-full-hierarchy; it only calls itself 'preferred'.

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