Argent

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

With no annotations, the description fully discloses polling behavior, thresholds, return object fields (settled, waitedMs, polls), and explains that settled=false means timeout reached. It also references the same tree as 'describe'.

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?

Description is efficient (~100 words), well-structured with purpose first, then mechanism and usage advice. No superfluous text.

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 no output schema, the description explains return value thoroughly. Complex tool with 4 parameters all covered. Sufficient for an agent to use correctly.

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 value by explaining default values, roles of each parameter, and the polling mechanism shared with 'describe'.

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 clearly states the tool blocks until screen content settles or timeout, using a specific verb 'Block until' and resource 'screen content settled'. It distinguishes itself from siblings like 'describe' and 'await-ui-element'.

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?

Explicitly states 'Use after a launch/navigation to wait for the UI to render before screenshotting or tapping', providing clear when-to-use context. No explicit when-not, but the context is adequate.

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

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

With no annotations, the description carries the full burden, and it delivers: it explains polling intervals, defaults, return shape, and the crucial nuance that success=false is not always a verdict on the condition, with cause values of unmet, unreadable, and cancelled. It also discloses selector matching pitfalls, reading order, hidden zero-area semantics, and the underlying accessibility/DOM sources. This is exemplary behavioral disclosure.

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 long but well-structured with headings and front-loaded purpose. Some condition details are repeated from the schema, which adds length, but the additional context about selector resolution, failure causes, and polling justifies most of the content. It is dense but organized enough for an agent 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?

Given 8 parameters, a nested selector object, multiple conditions, and no output schema or annotations, the description is remarkably complete. It explains the return value shape, failure semantics, when a failure licenses rewriting the check, and even the environmental tree types. There are no critical gaps that would prevent correct use.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains reading order for visible text matches, the loose-selector trap, the unqualified Android resource-id matching behavior, and the exact meaning of each condition. It clarifies expectedText and textMatch behavior contextually rather than merely restating the schema.

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: 'Block until a UI element reaches an expected state or a timeout elapses.' It clearly distinguishes itself from polling screenshot/describe by stating it removes that need, and the conditions section further defines exact behavioral scope. This is much more than a tautology and stands apart from sibling tools like describe and await-screen-idle.

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 final sentence gives explicit usage guidance: 'Use this after a tap/navigation to wait for the next screen, or before tapping an element that appears asynchronously.' It also explicitly contrasts with polling screenshot/describe yourself. It does not formally enumerate when not to use it or name all sibling alternatives like await-screen-idle, so it stops short of a 5.

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

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

With no annotations present, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool waits until the target is ready, returns a tagged payload, can take 2–10 minutes on Android, hot-boots from snapshots with cold-boot fallback, and terminates spawned devices on Android/Electron boot failure. This is unusually rich operational transparency.

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?

Although long, the description is dense and well structured: core action first, then platform selection, usage timing, return shapes, and operational caveats. Every sentence carries information needed to invoke the tool correctly, and the critical selector rule is front-loaded.

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 complex four-platform tool with 10 parameters, no annotations, and no output schema, the description is complete. It explains return payloads for every platform, mutual exclusivity of platform-selector parameters, boot durations, snapshot behavior, and failure cleanup. The schema handles remaining platform-specific parameter details.

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. The description adds cross-parameter meaning by explaining that the passed argument selects the platform, that Android assigns a serial automatically, and that a CDP port is auto-picked unless electronPort is supplied. This is more than a per-field schema listing provides centrally.

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 verb and resource: start an iOS simulator, launch an Android emulator, start a Vega VVD, or spawn an Electron app. It also explains that each platform is selected by a specific argument, which makes the tool's purpose distinct from siblings like list-devices and launch-app.

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 gives clear usage context: 'Use at the start of a session once you have picked a target.' It also explains that the choice of platform is determined by which argument is passed. However, it does not explicitly name when-not-to-use cases or contrast with post-boot tools like launch-app or restart-app.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses platform-specific event injection behavior (iOS Down/Up vs Android adb keyevent), unsupported-button rejection, the return value shape, and failure conditions when the backend is unreachable. This is exceptionally transparent for a tool with no annotations.

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 detailed but every sentence earns its place: platform behavior, supported buttons, usage intent, return value, and failure modes. It is front-loaded with the core action and structured logically, making it easy for an agent to parse quickly.

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?

Despite having no output schema and no annotations, the description covers return format, failure conditions, platform specifics, and supported values. Given the moderate complexity of this tool, nothing essential is missing for an agent to select and invoke it correctly.

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 schema already describes both parameters with useful descriptions. The description goes beyond the schema by explaining platform-specific meaning of the button enum, which buttons are rejected on which platforms, and how the press is actually injected. This adds genuine value beyond the structured field descriptions.

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 verb ('Press') and resource ('device hardware button'), with platform scope explicitly covered. It clearly distinguishes itself from sibling gesture and keyboard tools by focusing on hardware buttons and even gives platform-specific examples.

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 provides an explicit usage sentence: 'Use when you need to trigger hardware button events.' It also clarifies platform-dependent behavior and which buttons are rejected, giving practical guidance. It does not explicitly mention alternatives like gesture-tap or keyboard, but the hardware-button focus makes the intended use clear.

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

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

With no annotations, the description carries the burden. It discloses that HttpOnly cookies are included, the actions are destructive (e.g., 'clear removes ALL browser cookies'), and failure cases (non-Chromium device, missing params). It also describes return values for each action. Missing details on idempotency or rate limiting, but covers major behaviors.

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 well-structured with a clear introduction, bulleted action list, usage guidance, return types, and failure conditions. It is front-loaded with the core purpose. A minor reduction for length, but every sentence serves a purpose.

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 11 parameters, 4 actions, no output schema, and no annotations, the description covers purpose, usage, parameter roles by action, return values, and failure conditions. It lacks details about the format of returned cookie objects, but overall provides sufficient context for an agent to use the tool correctly.

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 value by grouping parameters per action (e.g., 'action="get" (url?)... defaults to the active page'), which provides context beyond the schema's individual parameter descriptions. It clarifies which parameters apply to which actions.

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 verb ('Read and write') and resource ('cookies of a Chromium (CDP) app'), and enumerates four distinct actions (get, set, delete, clear). It clearly distinguishes the tool's scope from siblings like 'chromium-storage' which handles other storage types.

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 says when to use the tool: 'Use when seeding an authenticated session before a flow... or asserting cookie state after one.' It also notes Chromium-only requirement and failure conditions. However, it does not mention alternative tools for related tasks (e.g., localStorage), leaving some ambiguity.

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

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

No annotations, so description covers all behavioral traits: lists actions, return values, failure conditions (non-CDP, missing keys), per-origin scope. Comprehensive.

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?

Well-structured with bullet points, front-loaded main purpose, no fluff. Each sentence adds value.

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?

No output schema, but description fully explains return shapes for all actions, constraints (Chromium-only), and failure reasons. Complete for a 5-param, 4-action tool.

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 100% with descriptions. Description adds return format details and action behaviors beyond schema, e.g., value vs entries+count, status objects.

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?

Clearly states 'Read and write localStorage/sessionStorage of a Chromium (CDP) app's active page.' Specific verb and resource, distinct from siblings like chromium-cookies or chromium-tabs.

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?

Explicitly says 'Use when seeding feature flags / auth tokens before a flow or asserting persisted app state after one.' Provides context but no explicit when-not-to-use or alternatives.

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

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

Discloses all behavioral traits: actions, tab stability, default active tab, closure behavior, return format, and failure cases. No annotations so description carries full burden, which it meets thoroughly.

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?

Well-structured with bullet points for each action, clear and efficient language. Every sentence adds value, no wasted words.

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?

Covers all aspects: all four actions, preconditions, return value, failure modes, and Chromium-only restriction. No output schema, but return structure is described. Complete for a tool of this complexity.

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%, but description adds valuable context such as tabId stability, label interchangeability, and default for close. Exceeds baseline of 3 by providing extra information beyond schema descriptions.

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?

Clearly states it lists, switches, opens, and closes tabs/windows of a Chromium (CDP) app, distinguishing from sibling tools by specifying the target platform and actions.

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?

Provides explicit guidance on when to use (multiple windows/tabs, to inspect/drive a different page, open/close during flow) and failure conditions. Does not explicitly mention alternatives but context is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It discloses that off-screen components and wrappers are pruned, coordinates are normalized in [0,1] space, positions may shift, and it fails if Metro is not connected. It also explains the effect of maxNodes (collapsing chains) and includeSkipped (summary). This is comprehensive and transparent.

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 detailed but every sentence earns its place. It is front-loaded with the purpose, then structured with a numbered workflow and clear call-to-action. It avoids redundancy and uses bullet-like lists for readability. The length is justified by the tool's complexity and the absence of annotations.

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 5 parameters, no annotations, and no output schema, the description covers everything an agent needs: what it returns (text tree with coords), how to use it (workflow), when to re-call, failure conditions, parameter nuances, and even the purpose of includeSkipped. It also references the argent-react-native-app-workflow skill for more info, making it self-contained enough for correct invocation.

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?

Although the schema covers 100% of parameters, the description adds valuable context: device_id must match the one passed to debugger-connect, maxNodes collapses wrapper chains to preserve structure, onScreenOnly defaults to true and can include off-screen content, and includeSkipped provides a filtered summary. These explanations go beyond the schema descriptions, though not exhaustively (e.g., exact output format is only implied).

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 clearly states the tool's purpose: fetching the current screen as a compact component text tree with normalized tap coordinates. It explicitly says this is the preferred element discovery tool for React Native apps, distinguishing it from sibling tools like debugger-inspect-element or native-find-views. The verb+resource combination is specific and unambiguous.

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 provides a clear workflow: call the tool, find the element by name/text/testID/accessibilityLabel, then use the tap coordinates. It also tells when to call again (after navigation/state changes) and when to use includeSkipped. It explicitly states it is the preferred tool for React Native and mentions it fails if Metro is not connected, giving agents clear go/no-go conditions.

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

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

The description discloses important behavioral traits: it returns existing connection if already connected, ignores port for Chromium, and fails on unreachable runtime. It also explains the return value structure (connection info fields). While annotations are absent, the description carries the burden well by explaining idempotent behavior and failure modes.

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 well-structured with a clear opening sentence, platform-specific details, return value summary, usage guidance, and failure conditions. Every sentence adds value, and the most important information (what it does, when to use it) is front-loaded.

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 connection tool with 2 parameters and no output schema, the description is complete. It covers what the tool does, platform variations, return values, idempotent behavior, usage context, and failure modes. An agent has everything needed to call it correctly.

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 schema already documents both parameters. The description adds value by explaining the port's platform-specific behavior (ignored for Chromium) and the device_id's stability guidance ('Pass this SAME id... you do not switch to it'). This goes beyond the schema's basic descriptions.

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 clearly states the tool's purpose: 'Connect to a JS runtime CDP debugger.' It specifies the verb (connect), the resource (JS runtime CDP debugger), and distinguishes between platforms (iOS/Android/Vega vs Chromium). It also differentiates from siblings by noting it's the prerequisite for other debugger-* tools.

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 states when to use this tool: 'Use when starting a debug session or before calling other debugger-* tools.' It also provides platform-specific guidance (Chromium re-uses existing session, port ignored) and failure conditions ('Fails if the runtime is unreachable'). This is clear usage guidance with no ambiguity.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it explains serialization-by-value, cyclic object failures, expression throw behavior, and runtime disconnection failures. This is substantial beyond the basic action.

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?

Four dense sentences, all earning their place. The core action is front-loaded, followed by return value context, usage guidance, and critical failure caveats. No filler.

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 no output schema and no annotations, the description covers the essential operational contract: runtime environment, return shape, common failure modes, and when to invoke. An agent has enough to select and call it correctly.

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 description coverage is 100%, so the baseline is 3. The description does not add much parameter-level meaning beyond the schema, though it does clarify evaluation semantics and failure behavior for the expression parameter.

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?

States a specific action: execute arbitrary JavaScript in the app's JS runtime via CDP, and names the relevant runtimes (Hermes/V8). This clearly differentiates it from sibling debugger tools like debugger-connect, debugger-status, and debugger-component-tree.

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?

Explicitly says when to use it: 'Use when you need to read app state, call app functions, or test logic at runtime.' It does not name alternatives or state when not to use it, so it falls just short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals ordering semantics (lowest indices are most specific), default limits (35 items), the internal mechanism (getInspectorDataForViewAtPoint, _debugStack, Metro symbolication), option effects (resolveSourceMaps, includeSkipped), and explicit failure modes. This is comprehensive for a read-only inspection tool.

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 detailed yet tightly written, with the core purpose and output behavior front-loaded. Every sentence earns its place: ordering, defaults, options, use case, and failure conditions are all useful and non-redundant. The structure moves naturally from what it does, to return semantics, to configuration knobs, to when to use it.

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?

Even without an output schema, the description explains what the response contains (components, source file:line, code fragment), how to interpret ordering, how to get more items, and what happens on failure. Parameter coverage is fully handled by the schema. This is a complete, self-contained definition for the tool's complexity.

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?

The input schema already documents all 8 parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: maxItems=70+ for navigation context, resolveSourceMaps=false for raw locations, and includeSkipped for filtered items with skip reasons. It doesn't add value for port, device_id, or contextLines, but the schema covers those adequately.

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 verb and resource: 'Inspect the React component hierarchy at a screen coordinate (x, y)' and explains the output in concrete terms ('components from the tapped element upward through its parent hierarchy, each with its source file:line and a code fragment'). This clearly differentiates it from sibling tools like debugger-component-tree by anchoring on a tap coordinate and source mapping.

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 includes an explicit use case: 'Use when you need the source file and line for a component at a tap coordinate.' It also warns about failure conditions (app not connected, coordinate outside the screen). However, it doesn't explicitly contrast this with sibling alternatives such as debugger-component-tree or native-view-at-point, so it falls short of full alternative routing.

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

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

With no annotations, the description carries the full transparency burden and does so thoroughly. It discloses the lifecycle: empty stats meaning, the special { note } for stop-all-simulator-servers, the not_connected response shape, guidance not to retry, and the stale-socket caveat. Nothing is hidden.

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 long but every sentence carries distinct behavioral value: purpose, platform support, usage guidance, serialized edge cases, and failover behavior. It front-loads the purpose and then groups subordinate caveats so an agent can quickly extract the main contract.

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 no output schema and no annotations, the description covers the successful summary fields, empty-result ambiguity, not_connected shape, retry guidance, and stale-session caveat. A sufficiently informed agent can invoke it correctly and know how to interpret every notable outcome.

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 schema already gives strong per-parameter semantics for port and device_id. The description adds no extra parameter-level information, so the baseline of 3 is appropriate; it neither confuses nor improves on the schema.

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 names a specific verb and resource: 'Get a summary of all console logs captured from the app's JS runtime.' It further lists concrete outputs (log file path, counts by level, message clusters) and the supported runtimes, making it easy to distinguish from siblings like debugger-status, debugger-evaluate, or view-network-logs.

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?

Explicitly says when to use it ('when investigating warnings, errors, or unexpected output'), how to sequence it ('call this first... then read the returned file'), and what not to rely on it for ('use debugger-status, not this tool, to judge debugger health'). This gives the agent clear decision rules.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the return value structure, indicates success/failure conditions, and mentions the port ignored condition for Chromium. However, it does not detail potential side effects (e.g., losing JS state, recompiling) or exact behavior beyond the reload path. Since it covers key aspects but lacks depth, a 3 is fair.

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 concise, with the core purpose stated in the first sentence and usage guidance in the second. It is front-loaded and each sentence adds value. A slightly lower score would be due to minor redundancy in explaining the return value, but overall it's efficient.

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 two parameters, one required, and no output schema, the description covers the return structure and failure condition, making it adequately complete for basic use. However, it could benefit from noting typical use cases or prerequisites (e.g., that a debugger session must be connected first). The given context is sufficient but not exhaustive, so a 3 is appropriate.

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 description coverage is 100%, so the parameters are well-documented in the schema. The description adds context by explaining the port's optional nature and the Chromium exception, which is helpful but not groundbreaking. It doesn't introduce new semantics beyond the schema, so baseline 3 is justified.

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 clearly states the tool's action (restart the Metro JS bundle) and the resource (connected React Native app) without restarting native. It distinguishes it from related tools by noting it does not restart the native process and mentions it fails if Metro isn't running. The purpose is specific and unambiguous.

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 states when to use it: 'when you want to apply code changes or reset JS state.' It implicitly contrasts with native restarts and sibling tools like 'restart-app' and 'stop-metro', making the usage context clear. However, it does not explicitly state when not to use it or name alternative tools, so a 4 is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains that the tool never fails on unreachable runtimes, enumerates all possible discriminated-result statuses and reasons, and documents important edge cases like Chromium port omission, source map waiting, and legacy Metro behavior.

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 long but every sentence earns its place, especially given the absence of an output schema. It is front-loaded with purpose and usage, then uses structured bullets to communicate a complex discriminated result without wasted words.

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 only two parameters, no annotations, and no output schema, this description is unusually complete. It covers selection context, success and failure shapes, field semantics, failure reasons, platform-specific behavior, and follow-up guidance, so an agent has everything needed to call and interpret the tool correctly.

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?

The input schema already has 100% parameter coverage with detailed descriptions for both port and device_id, so the description is not required to compensate. The description adds no meaningful parameter semantics beyond what the schema already states, keeping this at the baseline of 3.

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 verb and resource: 'Get JS runtime debugger connection status and diagnostic info.' It also distinguishes the tool from the broader debugger-tool family by framing it as a connectivity check to run before other debugger tools, which is enough for an agent to tell it apart from siblings like debugger-evaluate or debugger-connect.

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?

It gives an explicit when-to-use instruction: verify connectivity before using other debugger tools, and adds operational guidance to follow the guidance field rather than retry in a loop. However, it does not name specific sibling alternatives or state when not to use it, so it falls just short of full alternative/exclusion guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses platform-specific implementation details, coordinate normalization, lack of z-order/occlusion information, Vega's empty-tree retry behavior, TV focus-driven output, and the physical iOS device limitation. It also explains the return shape { description, source } and how to compute tap coordinates.

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 long but every section earns its place given the multi-platform complexity. It is front-loaded with the core purpose, then organized by platform, return format, caveats, and alternatives. There is no redundant filler or restatement of the tool name.

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?

The tool has no output schema and no annotations, so the description must fully compensate. It covers platform-specific behaviors, return format, coordinate system, tap calculation, limitations, fallback suggestions, and sibling alternatives. Nothing an agent needs to invoke and interpret this tool correctly 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. The main description does not add much parameter-specific meaning beyond the schema, but the schema itself already documents udid and bundleId, including bundleId's fallback behavior and platform limitations. Thus the description adds no significant extra value here.

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: 'Get the accessibility / DOM element tree for the current screen.' It then clarifies what this means across iOS, Android, Chromium, and Vega, and explicitly distinguishes itself from native-describe-screen and debugger-component-tree, so an agent can select it correctly among many 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 gives explicit when-to-use guidance: use native-describe-screen for app-scoped UIKit inspection, use debugger-component-tree for React Native component names, and use tv-remote on TV targets. It also provides platform prerequisites such as launching com.apple.springboard before reading system dialogs on physical iOS devices.

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

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

No annotations provided, so description carries full burden. It discloses return value format, failure conditions (negative hours, persistence failure), and the side effect of suppressing notifications. Adequate for a state-changing tool.

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?

Two sentences, front-loaded with action, no unnecessary words. Every sentence adds value, making it highly concise and well-structured.

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 simple tool with one parameter, no output schema, and no nested objects, the description covers purpose, usage, behavior, and failure conditions completely. Nothing essential 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% with description for 'hours' including minimum and purpose. The description adds 'given number of hours' and 'suppression duration', but does not provide new meaning beyond what the schema already states. Baseline 3 is appropriate.

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?

Description clearly states 'Clear the Argent update notification', which is a specific verb+resource. It defines the tool's action well but does not explicitly differentiate from siblings like 'update-argent', though the purpose is clear and distinct.

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?

Provides explicit usage context: 'Use when the user asks to postpone or silence update reminders.' It does not list alternatives or when not to use, but the context is clear and the failure conditions are noted.

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

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

With no annotations provided, the description carries the full burden. It discloses the return shape ({ message, stepCount, savedTo }) and the failure condition (no recording in progress). It also explains the side effect of echoing a message when replayed. Absent are details about mutations to the flow file, but the behavior is adequately characterized.

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 compact and front-loaded: it states the purpose in the first sentence, then provides usage guidance, return information, and failure condition in a few sentences. Every sentence earns its place with no redundancy.

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?

The description is complete for this tool's complexity: it explains what the tool does, when to use it, what it returns, and a key error condition. Even without an output schema, the return shape is explicitly stated, making the tool's behavior fully comprehensible in context.

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?

The input schema has 100% coverage, with each parameter described (name, project_root, message). The description's mention that `name` + `project_root` identifies the flow is already embodied in the project_root schema. Thus the description adds no significant semantic value beyond the schema, matching the baseline for high schema coverage.

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 clearly states the tool's function: 'Record an echo step in the flow named by `name` + `project_root`' and explains that echo steps print a message on replay, distinguishing it from flow-add-step. It is specific and unambiguous.

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 provides explicit guidance: 'Use when you want to annotate a recorded flow with a human-readable label or checkpoint message.' It also notes the failure condition when no recording is in progress. However, it doesn't explicitly name alternatives like flow-add-step, so it stops short of a full alternatives comparison.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds valuable context: failed scripts are not recorded, and the agent should check `reason` and affected state before retrying. This goes beyond the basic operation and warns about failure semantics.

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?

Four sentences, each earning its place: purpose, usage condition, invocation guidance, and failure/retry behavior. The most important scoping and safety details are front-loaded without redundancy.

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 no output schema and no annotations, the description covers the essential context: input, placement, relationship to recording state, and failure behavior. It does not detail return values beyond the `reason` hint, but that is a minor gap for this tool.

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 description coverage is 100%, so the schema already documents all parameters. The description mainly repeats that `name` and `project_root` must match `flow-start-recording`, which is already stated in their schemas. No meaningful new parameter semantics are added.

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 clearly states the action: run a local .mjs file and record it as a `script:` step in an active flow. It distinguishes this from siblings like flow-add-step and flow-add-echo by naming the specific step type and file source.

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?

It explicitly scopes usage to when the user requests a local script in the flow, and it gives the critical consistency requirement of matching `name` and `project_root` from `flow-start-recording`. It does not name an alternative tool, but the exclusion is clear enough.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It covers prerequisite state, special mapping of `gesture-tap` and `restart-app`, the exact return shape, the semantic meaning of `recorded`, and the failure mode of failing with an error and recording nothing.

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 main purpose and usage context are front-loaded, and every sentence adds operational information. The passage is slightly dense with edge-case details, but nothing is extraneous or redundant with the schema.

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 recording mutation with no annotations and no output schema, this description covers prerequisites, command constraints, return semantics, and error behavior. An agent has enough information to invoke the tool correctly and interpret the result without additional inference.

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 parameters are already documented well. The description adds value by clarifying how `name` and `project_root` jointly identify the recording, restricting `command` to executable MCP tools rather than flow directives or recording tools, and providing an example JSON string for `args`.

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?

States a specific action: execute one MCP tool and record it as a flow step. It identifies the unique resource as the flow named by `name` + `project_root`, and distinguishes itself from the recording-tool siblings by telling agents to call `flow-add-script` directly.

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 an explicit use case: when recording a flow and each action should be executed and captured. It notes the prerequisite that recording must already be open, and names the alternative path for script steps via `flow-add-script` while warning against passing recording tools as the `command`.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful runtime behavior: 'Returns a per-step report: the first failure stops the run and the rest report as skipped.' This goes beyond the schema and helps the agent predict execution semantics, though it does not warn about side effects of actually running flows on a device.

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 compact and front-loaded with the core purpose. Every sentence earns its place: when to use, which alternatives to prefer, the one-source rule, and return behavior. There is no redundant repetition of parameter details already covered in the schema.

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 complex 8-parameter schema with 100% coverage and no output schema, the description supplies the missing high-level context: return format, stop-on-failure semantics, and source selection rules. The combination of a concise main description and richly documented parameters leaves an agent with enough information to invoke the tool correctly.

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 description coverage is 100%, so the baseline is 3. The main description adds value by enforcing the mutual-exclusivity rule for name and flow_path, and by clarifying where 'name' is resolved (under project_root). Since the parameter-level schema is already rich, this extra semantic guidance is useful but not extensive.

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?

Description states a specific verb and resource: 'Run a saved YAML flow end to end.' It clearly differentiates from sibling tools by naming gesture tools for one-off interactions and flow-start-recording for authoring a flow. The use cases (replay recorded path, re-run QA regression, check a known journey) further clarify intent.

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 says when to use this tool and when not to: use it for replaying recorded paths or QA regression, use gesture tools for one-off interactions, and use flow-start-recording to author a flow. It also provides the key routing rule 'Pass exactly one flow source: name or flow_path,' giving actionable guidance beyond the schema.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior, and it does so thoroughly. It explains side effects (leaving other recordings untouched), the return shape, failure conditions, and the nuanced warning propagation/dropping behavior for hand-edited YAML, cross-tree warnings, unmet waits, and UNKNOWN conditions. It even notes that the YAML can still be edited afterward.

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 long but dense, with no filler. Core purpose, return value, and usage guidance are front-loaded in the first paragraph, while the later paragraphs explain important warning and replay semantics that genuinely affect how the result should be interpreted. It could be tightened, but every sentence earns its place.

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's complexity, the absence of annotations, and the absence of an output schema, the description is remarkably complete. It covers the return keys, the failure condition, the subtle warning behavior, what to read before replaying, and the option to edit the YAML afterward. An agent has enough context to invoke the tool and interpret the result correctly.

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?

The input schema already provides full descriptions for both parameters, with 100% coverage. The description reinforces that `name` and `project_root` together identify the recording and must match the values passed to flow-start-recording, but this adds only marginal meaning beyond the schema's own wording. Schema coverage does the heavy lifting here.

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: 'Finish recording the flow named by `name` + `project_root`' and distinguishes this from related recording tools by stating it finalizes the flow and returns the recorded steps plus final YAML. It also gives the exact use case: 'Use when you have added all desired steps and want to finalize the flow file.' This clearly separates it from siblings like flow-add-step.

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 gives clear context for when to use the tool: after all desired steps have been added and the flow file should be finalized. It also states a precondition/failure mode: 'Fails if that flow has no recording in progress.' It does not explicitly enumerate alternatives or when-not-to-use cases, but the usage context is unambiguous.

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

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

No annotations are provided, so the description carries the full burden, and it does so thoroughly. It discloses the return shape, the empty-result behavior when no prerequisite is declared, the fact that no device is touched, that no simulator/emulator needs booting, that it is just a file read, and that it fails if the file does not exist.

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 front-loaded and logically ordered, with no filler, but it is somewhat dense and repeats the name/flow_path distinction and the flow location. These repetitions reinforce important constraints, so the slight redundancy costs only one point.

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?

With no output schema and no annotations, the description covers all essential context: what is returned, what empty means, what a prerequisite represents, failure behavior, cost/risk profile, and parameter constraints. An agent can decide whether to call it and construct a correct call without needing extra information.

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 already 100%, but the description adds critical cross-parameter semantics: name and flow_path are mutually exclusive, supplying both or neither is rejected, name resolves under project_root/.argent/flows/, and flow_path must be supplied through the file-input boundary. This materially improves correct invocation beyond the schema alone.

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 object: 'Read the execution prerequisite of a flow without running it', and clearly scopes the resource to a saved flow from .argent/flows/ or a boundary-managed flow_path. It also distinguishes itself from siblings by repeatedly stressing that executing the flow is not what this tool does.

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 says when to use it: before committing to a run, to check whether the device is already in the expected state, or to relay a precondition to a human. It ties addressing to flow-execute ('Address the flow exactly as you will address it in flow-execute'), giving the agent a clear alternative and preventing misuse.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the return shape, the co-located vs remote tool-server file behaviors, failure conditions, concurrency isolation, and the rule that steps run LIVE. It even explains nuanced cases like recorded checks returning success:false and the consequences of mid-recording edits. This is exceptionally transparent.

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 long but front-loaded and well-structured: purpose, return value, environment behavior, concurrency, follow-up actions, and caveats each occupy a coherent section. Every sentence adds needed operational context for a tool that starts a multi-step workflow. There is no tautology or filler.

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?

With no annotations and no output schema, the description covers the intent, lifecycle, parameter semantics, return envelope, failure modes, concurrent-recording behavior, and follow-up tools. Minor omissions like authentication requirements and a concrete YAML example do not prevent correct invocation. This is complete for the tool's complexity.

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 meaningful semantics beyond the schema: name + project_root key concurrent recordings, executionPrerequisite is fragment-only and must not be combined with a launch step, and project_root determines where the file is written. This extra context justifies a score above baseline.

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 action, 'Start recording a new flow', and immediately states the destructive/reset semantics: 'resetting .argent/flows/<name>.yaml to an empty flow and replacing any existing one.' It clearly positions the tool in the flow-recording lifecycle, distinguishing it from siblings like flow-add-step, flow-finish-recording, and flow-execute. The purpose is unambiguous.

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?

It explicitly says 'Use when you want to capture a reusable sequence of device interactions for later replay' and offers concrete route selection: for a self-contained e2e flow 'record a restart-app... as the FIRST step', while for a reusable fragment 'pass executionPrerequisite instead.' It also names the follow-up tools and warns about live execution and concurrency, so an agent knows exactly when and how to invoke this tool.

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

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

Discloses partial data behavior: 'Returns partial data if workspacePath does not exist or is not readable; missing items are represented as null or empty collections.' Also states failure conditions: 'Fails if the workspacePath is not an absolute path or the directory cannot be accessed.' No annotations to contradict.

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 well-structured and efficient, starting with a one-line summary, then detailing returned data, usage instructions, and behavior. It avoids redundancy, though it is slightly long due to the extensive list of returned fields; each field adds value.

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 complexity of the tool (returns many data points) and no output schema, the description fully enumerates all returned items and covers edge cases (partial data, failure modes). No gaps in what the agent needs to know.

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 description coverage is 100% for the single parameter, providing an absolute path example. The tool description does not add additional semantics beyond the schema, which is already adequate. Baseline score 3 is appropriate.

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 clearly states the tool's purpose: 'Fetch a structured snapshot of a mobile app project's workspace.' It enumerates the specific data returned (package.json, metro config, etc.), and distinguishes itself from siblings, which are mostly device interaction and debugging tools.

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?

Explicitly tells when to use (inspect project configuration) and when not to: 'DO NOT RUN THIS TOOL IF YOU ARE THE MAIN AGENT AND THIS TASK CAN BE DELEGATED TO A SUBAGENT.' Provides a clear usage sequence: 'If you are a subagent... run this as the first step.' Also recommends follow-up tools (Read/Glob/Grep).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains coordination normalization, delay defaults, interpolate behavior, return values, platform-specific limitations on physical iOS, and failure conditions. This is exemplary transparency for a gesture automation tool.

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 long but every section earns its place: purpose, alternatives, key parameter semantics, physical iOS caveats, return values, failure modes, and four illustrative examples. It is front-loaded with the most important routing information and organized so an agent can quickly understand when to use it and how to construct events.

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 no output schema, the description thoroughly explains what the tool returns, when it fails, and how platform differences affect behavior. The examples cover the main complex gesture types and the interpolate option, making the tool's expected invocation and results fully understandable.

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?

Although the input schema already documents all parameters, the description adds substantial semantic meaning beyond that. It explains how to compose event sequences for long-press, drag, smooth scroll, and pinch, gives concrete examples, and clarifies the meaning of delayMs and interpolate in the context of real gestures. This goes well beyond the baseline schema-provided information.

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 clearly states the tool's function: sending a sequence of touch events for complex gestures. It further distinguishes itself from siblings by naming specific use cases like long press, drag-and-drop, custom scroll, and two-finger pinch, while also calling out simpler alternatives. This makes the tool's purpose unambiguous and easy to differentiate.

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 gives explicit usage guidance: 'Use for: long press, drag-and-drop, custom scroll, pinch' and then explicitly routes simple taps to gesture-tap, straight-line scrolling to gesture-swipe, standard pinch to gesture-pinch, and rotation to gesture-rotate. It also provides physical iOS-specific constraints and failure conditions, leaving little room for incorrect tool selection.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the normalized coordinate system, the 1.0 edge-case behavior, the ~60fps interpolation, and the nuanced momentum/deceleration characteristics. It also states the return value and the failure condition when the CDP session is unreachable, leaving little to inference.

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 dense but every sentence earns its place. It front-loads the core operation, then covers coordinate semantics, use cases, alternatives, momentum behavior, and return/failure conditions in logical order. There is no filler or repetition that does not add value.

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 complex gesture tool with no annotations and no output schema, the description is fully complete. It covers coordinate mapping, edge cases, use cases, alternative tools, momentum semantics, the return value, and a failure mode. An agent has everything needed to select and invoke the tool correctly.

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%, which sets a baseline of 3. The description adds meaningful extra context beyond the schema: the shared coordinate space with gesture-tap and describe, the specific edge case where coordinate 1.0 lands one pixel inside the window, and the interaction between durationMs and momentum:false. While the schema already documents momentum and durationMs in detail, the description's coordinate-space clarifications elevate it above baseline.

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 precise, actionable definition: 'Press the left mouse button at a start point, move to an end point, and release — a desktop mouse drag in a Chromium app.' It names the exact resource and action, and immediately differentiates from sibling tools like gesture-tap (same coordinate space), gesture-scroll (does not scroll), and gesture-swipe (platform-specific).

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?

Explicitly states when to use the tool: 'Use for slider thumbs, drag-and-drop, text selection, or draggable UI elements.' It also gives direct alternatives: 'Dragging never scrolls content on desktop — use gesture-scroll for lists/pages' and 'on iOS/Android use gesture-swipe.' The momentum:false guidance adds a clear condition for a specific scenario.

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

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

No annotations provided, so description carries full burden. It discloses normalized coordinates, auto-generated frames at ~60fps, angle parameter, optional centroid drift, return value, and failure condition. Explains distance relationship for zoom direction.

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?

Single paragraph with ~7 sentences, front-loading purpose and coordinate system. Concise overall, but could be slightly more structured (e.g., bullet points for parameters). No wasted sentences.

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 9 parameters, no annotations, and no output schema, the description covers coordinate system, gesture mechanics, typical values, optional behavior, return format, and failure condition. Leaves little ambiguity for the agent.

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%, but description adds significant value: repeats coordinate normalization, gives typical values, explains drift mechanism, and clarifies start/end distance relationship. Exceeds baseline.

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?

Clearly states it executes a pinch-to-zoom gesture with specific verb and resource. Distinguishes from sibling gesture tools by noting same coordinate space as gesture-tap and gesture-swipe, but could be more explicit about when to use vs. gesture-rotate or gesture-custom.

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?

Provides a clear use case: 'Use when you need to zoom in or out on a map, image, or zoomable view.' But does not specify when not to use or mention alternatives beyond coordinate space hint.

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

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

With no annotations provided, the description carries full weight. It discloses normalized coordinates, auto-generated ~60fps interpolation, return value structure, failure conditions, radius override behavior, and rejection criteria for partially specified radiusX/radiusY. It even explains the physical ellipse vs. circle nuance—highly transparent.

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 detailed but every sentence adds value. It opens with purpose, then covers normalization, direction, typical values, parameter relationships, and failure modes. Structured logically with each paragraph addressing a key aspect. Despite length, it is tightly packed and front-loaded, with no redundant fluff.

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 complex gesture with 9 parameters and no output schema, the description covers all necessary aspects: physical interpretation of radius, angle semantics, coordinate space, failure rejection, return value, and frame rate. It fully compensates for the lack of annotations and enriches the schema. Complete for an agent to select and invoke correctly.

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%, but the description adds substantial meaning beyond the schema. It explains the coordinate space (normalized fractions), gives typical values (radius 0.15, startAngle 0, endAngle 90), clarifies that endAngle > startAngle is clockwise, and details how radiusX/radiusY interact with radius and override it. This aids correct parameter selection.

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 clearly states what the tool does: 'Send a two-finger circular arc gesture to rotate on-screen content by a specified angle.' It specifies the verb (send/gesture), resource (on-screen content), and scope (rotate by angle). It also distinguishes from sibling gesture-pinch by noting it 'orbits fingers in an arc to change orientation' vs. linear zoom.

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?

Provides explicit context: 'Use when you need to rotate a map, image picker, or any rotateable UI element.' It directly differentiates from gesture-pinch and notes the coordinate space shared with gesture-tap and gesture-swipe. Failure conditions are also mentioned (backend unreachable), giving clear guidance on when it may not work.

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

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

No annotations provided, so description carries full burden. It discloses the event type, coordinate space, return value, and failure condition (CDP session unreachable). Lacks details on default delta values or error messages, but covers core behavior well.

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 a single paragraph but well-structured with clear, informative sentences. It is appropriately sized for the complexity, though could be slightly more concise without losing meaning.

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?

With 6 parameters, no output schema, and no annotations, the description covers usage, platform, coordinates, return format, and failure. However, it does not specify default values for optional delta parameters (defaults to 0?), which is a minor gap.

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% with descriptions. The tool description adds value beyond schema by explaining normalization, coordinate space shared with other tools, and delta direction (positive scrolls down). Enhances understanding for all 6 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 description clearly states the tool scrolls content by dispatching mouse-wheel events. It specifies the coordinate system (normalized 0.0-1.0) and platform (Chromium). It distinguishes from sibling 'gesture-swipe' by noting Chromium-only vs iOS/Android.

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?

Explicitly tells when to use (content below/above fold, lists needing scrolling) and when not (use gesture-swipe on iOS/Android). Provides clear context and alternative.

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

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

With no annotations provided, the description carries the full burden and handles it thoroughly: it discloses interpolation at ~60fps, direction semantics, physical iOS quirks, momentum behavior, return shape, failure conditions, and the reactivated field. This goes far beyond a basic 'performs a swipe' statement and gives an agent concrete expectations for execution and results.

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 front-loaded with the core operation, but it quickly becomes a dense, run-on block of edge cases and empirical observations (e.g., '2 of 47 runs still flung backwards'). It also repeats much of the schema's momentum/duration text nearly verbatim, which adds length without new value. Every sentence carries some information, but the structure is not clean and the redundancy hurts conciseness.

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 complex gesture tool with no annotations and no output schema, the description is remarkably complete: it explains platform support, coordinate normalization, return value, failure behavior, timing constraints, momentum semantics, and physical-device caveats. An agent has enough context to invoke the tool correctly and interpret its result in most scenarios.

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; the description adds genuine extra meaning for parameters, notably that fromY > toY means swipe up to scroll down, that physical iOS edge gestures require fromX exactly 0, and that momentum:false requires durationMs >= 150. Much of the momentum and duration detail is redundant with the schema, but the unique insights push it above baseline.

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 clearly states a specific verb and resource: executing a smooth swipe/drag touch gesture between two normalized points. It names use cases (scroll, dismiss modal, navigate) and even an alternative for Chromium, but it does not fully differentiate from the sibling gesture-drag, which the description also claims to cover with 'drag an element.'

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?

It explicitly lists when to use the tool ('Use when you need to scroll a list, dismiss a modal, drag an element, or navigate between pages') and gives a clear when-not with an alternative ('Not supported on Chromium — use gesture-scroll there instead'). However, it does not clarify when gesture-drag or gesture-tap should be preferred, leaving some sibling differentiation to inference.

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

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 does so thoroughly. It details the Down/Up event sequence, Chromium CDP behavior, clickCount semantics across platforms, physical iOS reactivation behavior, return values, and failure conditions. This is far more transparent than typical tool 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?

Although the description is long, it is dense with necessary operational detail and every sentence adds value. The core action and coordinate system are front-loaded, followed by platform behavior, usage guidance, return values, and failure modes. The length is justified by the tool's complexity.

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?

The description is complete for a tool of this complexity: it covers coordinate interpretation, event semantics, double-tap behavior, platform-specific execution, return payload, failure modes, and how to choose discovery tools. With no output schema or annotations, this level of detail is exactly what an agent needs to invoke the tool correctly.

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?

The input schema already covers all 4 parameters with descriptions, so baseline is 3. The description adds meaningful semantics beyond the schema: it explains normalized coordinates, clickCount behavior for double-tap/double-click, cross-platform differences, and the guarantee of proper click counting. This raises it above baseline.

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 verb and resource: it presses the screen at normalized coordinates and sends a Down/Up event to tap a button, link, or tappable element. It clearly differentiates tap behavior from multi-tap and provides platform-specific semantics, making it distinguishable from sibling gesture tools like gesture-swipe or gesture-custom.

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 says when to use the tool ('Use when you need to tap a button, link, or any tappable element') and gives strong platform-specific guidance on which discovery tools to use before tapping. It does not explicitly name sibling alternatives like gesture-swipe or gesture-drag, but the usage context is clear enough for an agent to select this tool correctly.

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

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

With zero annotations, the description carries the full burden — and it delivers exhaustively. It discloses failure modes and their ordering (text+key rejected before anything is typed; unsupported key rejected up front; un-typeable text partially applied on iOS sim/Chromium but pre-checked on Android/Vega/TV), non-rollback semantics, retry guidance ('read the field's actual contents'), secret resolution behavior (server-side, echoed as placeholder, auto-screenshot skipped), and the reactivated flag on physical iOS.

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 long, but nearly every sentence earns its place given the tool's platform matrix, failure semantics, and secrets handling. It is front-loaded with purpose and organized into clear sections (usage, returns/failures, parameter details, TV specifics). It loses one point only because the density of caveats could tax an agent's parsing, and a few points (e.g., repeated 'one call does one action' admonitions) appear in both the prose and the schema.

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 4-parameter, multi-platform tool with no output schema and no annotations, the description is remarkably complete. It covers the return shape ({ typed, keys }), all failure modes with retry implications, platform-specific behaviors, the text OR key constraint, and cross-tool coordination with tv-remote and run-sequence. Nothing an agent needs to call this tool correctly 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?

Although schema coverage is 100% (baseline 3), the description adds substantial meaning beyond the schema: the secret placeholder mechanism with its full source-resolution order, the per-platform ignored conditions for delayMs, platform-specific key restrictions (TV targets, physical iOS limited to enter/backspace), and the character-set limitation on text. This materially changes how an agent would populate 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 description opens with a specific verb+resource pairing ('Type text or press special keys on the device') and enumerates the exact target surfaces (iOS simulator, Android emulator/device, Chromium app, Vega, TV). It distinguishes itself from sibling tools by naming what it is not — D-pad navigation belongs to remote tools — so an agent can differentiate it from tv-remote and the gesture family without opening schemas.

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?

Provides explicit when-to-use guidance ('Use when you need to enter text or trigger a named key') and clear exclusions ('On Vega and Apple TV / Android TV, prefer the remote tools for D-pad navigation'), plus a platform-specific rule ('NOT supported on TV targets; move focus with tv-remote instead'). It also instructs when to pair with run-sequence for multi-step actions, giving the agent a complete decision procedure.

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

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

There are no annotations, so the description carries the full burden, and it delivers: it discloses side effects (native-devtools injection, physical iPhone registration), behavior on Chromium (no-op refresh), failure conditions (app not installed), response shape ({ launched, bundleId, note? }), and warnings about runner signing. This is exceptionally transparent.

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 long but the complexity demands it. The core purpose is front-loaded, and each subsequent paragraph covers a distinct concern: usage preference, return/failure behavior, Chromium specifics, and platform ID examples. No sentence is wasted; the structure makes the dense information navigable.

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 multi-platform nature, the lack of annotations, and the lack of an output schema, the description is remarkably complete. It covers iOS, Android, Chromium, tvOS, and Fire TV, explains the return value, failure mode, and no-op behavior, and gives concrete examples. An agent has what it needs to invoke this correctly.

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. The description adds value beyond the schema by providing common iOS bundle IDs, common Android package names, the Vega/Fire TV manifest.toml source for bundleId, and clarifying Chromium's tag behavior. These practical examples and platform-specific hints make the parameters easier to use correctly.

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: 'Open an app by its bundle id (iOS) or package name (Android), or confirm the running renderer (Chromium).' This clearly identifies what the tool does and its platform scope. It also distinguishes launch-app from nearby tools like restart-app and open-url by indicating when each applies.

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 says to use this when starting any app and to prefer it over tapping home-screen/launcher icons. It also provides alternatives: use tv-* tools for tvOS focus interaction and use open-url for Chromium route changes. These explicit when/when-not/alternative cues are strong.

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

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

With no annotations, the description carries the full behavioral burden and delivers extensively: it discloses return shape ({ devices, avds }), platform discriminators, states (running/stopped/connected/paired), headless behavior for additional CoreSimulator devices, silent omission of platforms with unavailable CLIs, and empty-result meaning. No annotation contradiction.

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?

Although long, the description is front-loaded with the core purpose and usage, then organized in clear platform-specific paragraphs. Each sentence adds operational detail (discovery mechanism, state semantics, alternatives) rather than filler, so the length is justified.

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 multi-platform inventory tool with no output schema or annotations, and the description covers all the context an agent needs: return format, target-id selection, per-platform behaviors, prerequisites, state/ordering semantics, and failure interpretation. It is effectively self-contained.

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?

The tool has zero parameters and schema coverage is 100%, so the baseline is 4; there are no parameter semantics to document. The description instead adds meaning to the returned fields (udid/serial/id, kind, state, runtimeKind), which is more relevant than parameter docs.

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 opening sentence states a precise verb ('List') with an explicit resource scope: iOS simulators, Android emulators, connected physical Android devices, running Chromium apps, and Vega/Fire TV devices. It also distinguishes the tool from interaction-focused siblings like boot-device and tv-remote by saying it returns target ids to pass to them.

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 says to use it at the start of a session to pick a target id and see running targets. It names alternatives and conditions: use boot-device to boot stopped Vega devices and AVDs, no boot-device needed for physical phones, boot-device with electronAppPath for Chromium, and tv-remote/keyboard/describe for TV targets instead of gestures.

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

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

With no annotations, the description carries full burden. It thoroughly discloses return contents (flat list of leaf elements, frames, tapPoints, normalized fields, traits, labels) and behavioral quirks (statuses for not-connected apps, restart logic, service_stale requiring tool-server restart, connect_pending meaning do not restart, init_failed requiring simulator reboot, rejection of Apple system apps). This is exceptionally transparent.

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?

Despite being long, every sentence adds valuable information. It front-loads the core purpose, then details output, usage context, and error handling in a logical order. No fluff or repetition; the length is justified by the tool's complexity.

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?

The tool is complex (low-level native inspection with multiple statuses and failure modes) and lacks an output schema. The description fully compensates by explaining return values, usage scenarios, and detailed error recovery steps. It also clarifies the relationship with the describe tool, ensuring complete context for an agent.

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 all four parameters have descriptions in the schema (udid, bundleId, skipClasses, skipClassPrefixes) with helpful examples. The description does not add extra parameter semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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 clearly states the tool reads the running app's native accessibility screen description via injected devtools, and distinguishes it from the sibling 'describe' tool by calling it a low-level native inspection tool with raw point-space geometry. It explicitly mentions the separate public describe contract.

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?

Explicitly says 'Use when you are evaluating or debugging the lower-level native data behind the public describe tool, or when you need its raw point-space geometry rather than describe's normalized contract.' It also provides detailed status handling instructions (restart_required, service_stale, connect_pending, init_failed) and failure modes (Apple system app rejection), making when-to-use and how-to-handle conditions very clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It details the meaning of each return field (envSetup, appRunning, connected, requiresRestart, state, message, etc.), explains edge cases like 'stale_process', 'unregistered', 'connecting', and 'indeterminate', and clarifies terminal conditions. It also discloses failure behavior (init_failed, simulator server not running). No contradiction exists, and the description goes far beyond basic expectations.

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 lengthy but well-structured: it starts with purpose, then lists return fields with definitions, then provides a series of conditional action instructions. Each sentence carries necessary information given the tool's complexity. However, there is some redundancy between the state field description and the later action rules (e.g., 'stale_process' explanation appears twice). This slight repetition prevents a 5, but the overall organization is clear and front-loaded.

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?

The tool has a complex return structure with many possible states, and there is no output schema to rely on. The description explains every field, every state, and every recommended action, including failure modes and terminal conditions. It also covers remote simulator limitations. Nothing an agent needs to correctly interpret and act on the result 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?

The schema already fully describes both parameters (udid and bundleId) with 100% coverage, so the baseline is 3. The description adds semantic value by explaining how bundleId affects injectability (Apple system apps are not injectable) and how the parameters influence the tool's checks. This goes beyond the schema's simple labels, so a 4 is warranted.

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: 'Check whether native devtools are connected to a specific app and whether the next launch is prepared for injection.' It then explicitly states when to use it (before native-full-hierarchy, native-describe-screen, or native-network-logs), distinguishing it from sibling tools. The purpose is unambiguous and actionable.

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 gives explicit when-to-use guidance ('Call this before using app-scoped native hierarchy tools or native-network-logs') and then provides a comprehensive decision tree for every possible return state, including when to use alternatives like describe or screenshot, when to restart the app, and when to restart the tool-server. It even includes negative guidance (do NOT restart in certain states). This is exemplary usage guidance.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It explains return shape, each possible status with specific recovery actions, the fact that not-connected/running apps surface as statuses rather than failures, and failure cases such as Apple system app rejection and hierarchy query errors/timeouts.

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 front-loaded: purpose, when-to-use, return shape, constraint, then operational statuses. It is long due to complex runtime behaviors, but every sentence adds necessary guidance; the troubleshooting block is justified because there is no output schema or annotations to cover it.

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's complexity, 10 parameters, and no output schema, the description is remarkably complete. It specifies the return format, optional ancestors/children, required search criteria, status-specific recovery flows, and terminal failure cases, so an agent has enough context to invoke and recover from failures.

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?

The input schema already documents all parameters with 100% coverage, so the description does not need to repeat them. It adds meaningful cross-parameter semantics by stating that at least one of className, identifier, label, tag, or nativeID is required, which is not encoded in the schema itself.

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: 'Search for specific UIViews in the running app' and enumerates all search criteria (class name, accessibility identifier, label, tag, or nativeID). It differentiates from the closest sibling by stating 'Much more targeted than native-full-hierarchy.'

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?

It explicitly says when to use the tool: 'Use when you need to locate a specific view by its properties without dumping the entire hierarchy.' It also names the alternative native-full-hierarchy and emphasizes the at-least-one search-criterion requirement.

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

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.

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

No annotations are present, so the description carries the full burden, and it delivers: it enumerates possible statuses (restart_required, service_stale, connect_pending, init_failed), what each means, and what action to take. It also explains terminal failure cases such as Apple system apps and NATIVE_DEVTOOLS_NOT_CONNECTED, so an agent avoids retrying hopeless operations.

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?

It opens with a crisp statement of function and differentiation before moving into operational details. The longer status/failure sections are organized by status name, and each sentence adds a distinct recovery instruction, so the length is justified.

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 there is no output schema, the description fully specifies the return shape ({ status, count, events } and event fields) and all practical status/failure branches. Combined with the high-coverage parameter schema, an agent has what it needs to invoke and react correctly.

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%, with all four parameters already documented, so the baseline is 3. The description adds context about the return envelope and event fields, but it does not need to repeat parameter meanings and does not materially extend parameter semantics.

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 names a specific resource ('network requests at the native NSURLProtocol level') and a specific action ('Retrieve'), then contrasts it with view-network-logs. It explicitly identifies coverage of native modules, Swift/Objective-C networking, and background transfers, making the tool's scope unmistakable.

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?

It states 'Use when you need to inspect native-level HTTP traffic that is invisible to JS fetch interception' and names the alternative view-network-logs. It also provides status-by-status recovery guidance, including when not to retry/restart versus restarting the tool-server or simulator.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses platform-specific analysis behavior, the markdown report format, severity indicators, tables, actionable suggestions, and the follow-up interaction of asking the user before deeper investigation. It could be slightly more explicit about side effects, but for an analysis tool this is adequately transparent.

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 front-loaded and logically organized, covering platform details, output format, usage condition, and follow-up workflow. There is some redundancy: 'Call native-profiler-stop first...' and 'Fails if native-profiler-stop has not been called first...' repeat the same prerequisite. This minor duplication prevents a perfect score but the description is still concise enough.

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?

Despite having no output schema and no annotations, the description covers input, platform-specific behavior, output format, prerequisite, failure mode, and recommended next action. This is sufficient for an agent to decide when to use the tool, invoke it correctly, and handle the resulting markdown report appropriately.

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 description coverage is 100%, and the single device_id parameter is already well described with its source: 'Target device id from list-devices (iOS UDID or Android serial).' The main description does not add further parameter-specific meaning beyond what the schema provides. Therefore the baseline score of 3 applies.

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 action: 'Analyze exported native trace data and return an LLM-optimized markdown report.' It further specifies iOS XML parsing and Android Perfetto querying, giving clear resource and platform scope. This clearly distinguishes it from sibling tools like profiler-stack-query and react-profiler-analyze.

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?

It explicitly states when to use the tool: 'Use when you need to interpret a completed native profiling recording.' It also gives a prerequisite and failure condition: 'Call native-profiler-stop first' and 'Fails if native-profiler-stop has not been called first.' The reference to profiler-stack-query as a downstream drill-down option adds useful usage context.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses auto-detection behavior, return shape ({ status, pid, traceFile }), failure conditions, platform-specific behavior, and detailed trade-offs for malloc_stack_logging including app restart, overhead, Xcode limitations, and environment variable interactions.

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 long but every sentence earns its place. It is well-structured with platform breakdown, usage flow, return value, failure modes, and parameter-specific caveats, making it dense but not wasteful.

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's complexity (two platforms, four parameters, no output schema, no annotations), the description is remarkably complete. It covers return values, failure conditions, platform differences, and operational workflow, leaving no major gaps for an agent to misuse the tool.

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?

Although schema coverage is 100%, the description adds significant value beyond the schema: it explains when to provide app_process (only if auto-detection picks wrong app), that template_path defaults to a bundled Argent template and is ignored on Android, and gives extensive context for malloc_stack_logging including when to leave it off and when the call is rejected.

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 clearly states the tool starts native profiling on a booted device, with platform-specific details (iOS Instruments via xctrace, Android Perfetto). It distinguishes itself from sibling tools like react-profiler-start and native-profiler-stop by specifying native CPU, hang, and memory capture.

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 says 'Use when you want to capture native CPU, hang, and memory data for a running app' and instructs to call native-profiler-stop after user interaction. It does not explicitly contrast with react-profiler-start, but the native vs. React distinction is implied by tool naming and context.

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

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

No annotations are provided, so the description carries the full burden. It transparently describes the platform-specific behaviors (iOS vs Android), signals, polling, and pull operations. It discloses the failure condition (no active session). However, it does not describe side effects like whether profiling is terminated or any cleanup, but given the nature of stop, this is acceptable. It adds context beyond the simple stop action.

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 reasonably concise, with three sentences covering purpose, method, and usage. It front-loads the action. It includes platform details and return value info, but the length is moderate. It is structured well; the platform breakdown is clear. Slight improvement would be trimming redundant details, but it's acceptable.

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's complexity (platform-specific stops), the description covers key behaviors: signals, packaging, polling, exporting, return fields, and failure. It lacks an output schema, so it properly explains the return value. It's complete for an agent to select and invoke this tool, especially with the precondition 'Call native-profiler-start first.'

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% with a detailed description for device_id. The description reiterates the parameter's origin ('from list-devices') and platform-specific formats, which slightly adds value beyond the schema. It doesn't explain any additional parameter aspects, but with one parameter well-covered, this is sufficient.

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 clearly states the tool's purpose: stop native profiling and export trace data. It distinguishes from siblings like native-profiler-start and native-profiler-analyze by specifying the stop/export action. It is not just a verb+resource, but it does not explicitly mention that it is the inverse of start, though it says 'Call native-profiler-start first.'

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 provides concrete usage context: 'Call native-profiler-start first' sets a precondition, and 'Use when the user has finished the interaction to profile and you need to export the trace' gives a clear scenario. It doesn't explicitly mention when not to use or alternatives, but the 'call start first' is strong guidance.

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

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.

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

With no annotations, the description carries the full burden. It discloses the return format (status + view with class, frames, identifier, label, layer name, ancestor chain, subviews on request), the coordinate system (raw points, not normalized), and detailed error-handling for statuses (restart_required, service_stale, connect_pending, init_failed) and failure modes (system apps rejected). No contradictions with annotations since none are present.

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 long but well-structured: it opens with the core purpose, then contrasts with a sibling, gives a use case, describes return structure, and concludes with status handling. Every paragraph covers a distinct aspect and includes necessary operational details. It could be slightly trimmed but remains efficient given the tool's complexity.

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's complexity (10 parameters, 4 required) and the absence of an output schema, the description is exceptionally complete. It covers the return value structure, all expected statuses with recovery steps, coordinate system specifics, and Edge cases (system app rejection). It leaves no major gaps for an agent to successfully use the tool.

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?

The input schema provides 100% coverage of all 10 parameters, including descriptions for x/y coordinates and field lists. The description adds a warning about raw coordinates and clarifies default behavior (e.g., includeAncestors defaults true), but these are already in the schema. It does not significantly add value beyond what the schema documents, so the baseline 3 is appropriate.

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 clearly states it inspects the deepest visible UIView at a raw native window point, and explicitly contrasts with native-user-interactable-view-at-point, distinguishing it as answering 'what is visually here?' rather than 'what would receive the touch?'. This makes the purpose specific and distinct from 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?

It provides explicit when-to-use guidance: 'Use when a screenshot shows something the accessibility tree does not name — an unlabeled icon, a decorative overlay, a custom-drawn cell'. It also names the sibling alternative and explains the difference, fulfilling the when/when-not requirement fully.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals the Chromium renderer navigation behavior, the deep-linking caveat around Universal Links and App Links, physical iPhone Safari default behavior, the return shape, and failure conditions. This is far more than a generic 'opens a URL' statement and lets an agent predict outcomes accurately.

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 long but every sentence earns its place: it front-loads the core action, then gives platform schemes, deep-linking caveats, return values, and failure modes. It is organized into clear paragraphs, making it scannable. It could arguably be tightened, but the length is justified by the number of platform-specific behaviors that affect invocation.

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?

Despite having no output schema or annotations, the description is effectively complete for an agent to invoke the tool correctly. It covers supported schemes per platform, how deep links behave, how to route app openings to `launch-app`, what the return value contains, and under what circumstances the call fails. There are no critical gaps for a tool of this complexity.

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 description coverage is 100%, so the baseline is 3. The description adds some useful context around URL schemes and deep-linking behavior, but it does not substantially expand on the `url`, `udid`, or `bundleId` parameters beyond what the schema already documents. The schema already states defaults, requirements, and examples, so the description's added parameter-level value is minimal.

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: 'Open a URL or URL scheme on the device.' It then clarifies the two main uses—web navigation and app deep-linking—and explicitly contrasts with the sibling `launch-app` by naming it as the reliable alternative for opening an installed app. This gives an agent a clear mental model of what the tool is for and what it is not.

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 explains when to use the tool ('Use to navigate to a web page or deep-link into an app') and gives explicit exclusion guidance: to reliably open an installed app, use its custom scheme or `launch-app` with its bundle id. It also lays out platform-specific behaviors for Chromium, iOS, and Android, so an agent can choose the correct tool and URL form for the situation.

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

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

With no annotations provided, the description carries the full burden and does so exceptionally well. It discloses that only the device clipboard is affected (host clipboard untouched), that a paste shortcut is triggered, that it returns `{ pasted: true }`, and it lists specific failure conditions (TV target, clipboard failure, missing simulator-server support). It also explains the secret placeholder behavior and that secrets are never echoed back.

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 compact, front-loaded with the core behavior, and every sentence earns its place: mechanism, usage boundaries, prerequisites, return value, failure modes, and secret handling. No fluff or redundancy.

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?

The description is complete for a tool of this complexity. It covers what happens, when to use it, prerequisites, return shape, failure conditions, and security-relevant secret behavior. The absence of an output schema is mitigated because the return value is explicitly stated.

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?

Input schema coverage is 100%, with detailed per-parameter descriptions, so the baseline is 3. The tool description adds organic context beyond the schema: the text parameter's clipboard-vs-host behavior, the same-source relationship with `keyboard` for secrets, and the requirement that the target field have focus. This adds meaningful conceptual value, though the schema already documents the main mechanics.

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+resource: 'Paste text into the focused field', and explains the mechanism clearly (device clipboard + platform paste shortcut). It explicitly distinguishes itself from the sibling `keyboard` tool, both in purpose and in the user-action model.

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 gives explicit when-to-use guidance: use `paste` only where a real user would paste, such as 2FA codes, long links/tokens, or testing paste handling. It also gives a clear negative instruction: 'Do NOT use this in place of `keyboard`', and provides a prerequisite step ('Tap the field first').

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

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

Since no annotations are provided, the description must carry the full burden of behavioral disclosure. It does so well by stating critical behavioral aspects: it succeeds only after both profiler analyses have been called, and it fails otherwise ('Fails if either... has not been called first'). It also describes the return format ('markdown report'). This provides clear behavioral expectations for an agent, exceeding what a simple description might offer.

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 concise and well-structured: it front-loads the purpose (first sentence), then details the method (second sentence), prerequisites (third), usage timing (fourth), output description (fifth), and failure condition (sixth). Each sentence delivers essential information without extra fluff. The structure is logical, moving from what to how to when to the result and exceptions.

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 that there is no output schema and no annotations, the description must comprehensively explain what the agent can expect. It covers the tool's inputs (though schema does), behavior (prerequisites and failure), and output (markdown report contents). It doesn't explain the exact contents of the report beyond 'correlating hangs with React commits, memory leaks, and investigation hints,' which is sufficient for an agent to decide to use it. A slight gap is not mentioning how long the operation might take or if any other side effects occur, but overall it's well-rounded.

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 description coverage is 100%, so the schema already provides full descriptions for both parameters (device_id and port). The description adds minimal additional meaning beyond the schema, mainly clarifying the port behavior with 'Omit it to use this device's port, 8081 by default' and the device_id semantics as 'iOS Simulator/device UDID or Android serial'. Since the schema already covers this, the description adds limited extra value, baseline 3 is appropriate.

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 clearly states the tool's purpose: 'Generate a cross-correlated report combining React Profiler and native profiler data.' It specifies the verb (generate), the resource (cross-correlated report), and the method (wall-clock time alignment). This distinguishes it from sibling tools like profiler-cpu-query or react-profiler-analyze, though it does not explicitly name alternatives. A score of 4 is appropriate for clear purpose but slight lack of direct sibling differentiation.

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 provides explicit usage conditions: 'Call this tool when both profilers were run in parallel on the same session.' It also states important prerequisites: 'Requires both react-profiler-analyze and native-profiler-analyze to have been called first.' This gives strong guidance on when to use it, though it doesn't explicitly say when not to use it or name alternatives. Still, it implicitly differentiates from single-profiler tools by requiring both profilers.

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

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

With no annotations, the description carries the full burden, and it does well by disclosing the required prior call, failure conditions, and the markdown table/tree return format. It implies a non-mutating query operation, though it does not explicitly state that it leaves profiling state unchanged.

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 well-structured with a front-loaded purpose and a clean bulleted mode list. The only minor flaw is redundancy: "Requires react-profiler-stop to have been called first" is restated in the final failure sentence.

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 seven parameters, nested objects, no annotations, and no output schema, the description covers prerequisites, failure behavior, output shape, and mode semantics well. It does not explicitly state that certain mode-specific parameters like commit_index or time_range_ms are expected for their modes, which is a small but real completeness gap.

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 already 100%, which puts this at baseline 3, but the top-level mode descriptions add meaning beyond the schema by specifying what each mode reveals: causes and durations, props changed, and parent-child cascade relationships. The schema still carries most parameter detail, so this is not a 5.

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: "Query React commit data for iterative investigation of render performance." It then enumerates four distinct query modes, making it clear what the tool is for and how it differs from broader profiling tools like react-profiler-analyze.

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?

It explicitly says to use this tool when drilling into specific components or time windows after react-profiler-analyze, and states the hard prerequisite that react-profiler-stop must have been called first. It does not explicitly name exclusions or alternative sibling tools, but the usage context is clear.

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

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 does so thoroughly. It defines self-times as summed sampling intervals, explains that widening the query window does not change values, states that every table reports sample count and idle portion, and warns that the tool fails if no CPU profile is stored. This goes well beyond what the schema alone provides.

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 front-loaded with the core purpose and prerequisite, then uses a compact bulleted list for the four modes. The length is justified by the tool's complexity, and every sentence carries operational information such as sampling semantics, output format, or failure behavior.

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?

The description covers prerequisites, failure mode, output format, mode semantics, and the sampling caveat about self-times. Since there is no output schema, the explicit statement that it returns a markdown table of CPU hotspots, call tree, or per-component CPU breakdown is necessary and sufficient.

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 description coverage is 100%, so the baseline is 3. The description adds useful semantic context such as using time_window for a slow commit or hang, component_cpu aggregating across all commits, and the optional time_window_ms filter on top_functions. It mostly reaffirms schema descriptions rather than deeply enriching every parameter, but the added mode-level guidance justifies a score above baseline.

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: 'Query Hermes CPU profile data' and then enumerates four concrete query modes. This clearly distinguishes the tool from sibling profiler, render, and device-control tools by scoping it to Hermes CPU profile investigations.

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 states the prerequisite that react-profiler-stop (and ideally react-profiler-analyze) must have been called first, and it gives a clear use case: 'Use when investigating JS CPU hotspots or correlating CPU cost with specific components.' It does not explicitly name sibling alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and does well: it states the operation is a disk-to-memory restore, describes the side effect of making data available to query tools, and discloses failure conditions ('Fails if the session_id is not found or required XML files are missing'). It does not discuss memory footprint or concurrent-session behavior, but the core behavioral profile is clear.

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 well-structured with a purpose sentence, sibling-context sentence, usage sentence, mode list, and return/failure statement. It is slightly long but each section serves a distinct purpose, and key information such as mode requirements is clearly isolated.

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 five parameters, no output schema, and no annotations, the description still covers all invocation-critical details: mode semantics, required parameters, optional app_process behavior, return shape at a high level, and failure modes. An agent has enough to select and call this tool correctly.

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 each parameter already has a description. The tool description adds extra value on top by explaining the mode-specific roles of session_id, device_id, and app_process, including the Android .pftrace edge case. This goes beyond simply restating schema text.

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: 'Fetch and restore a previously captured profiling session from disk into memory so query tools can operate on it.' It explicitly distinguishes itself from sibling tools by naming the write counterparts and the query tools, leaving no ambiguity about its role.

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 tells the agent exactly when to use this tool: 'Use when you need to revisit past session data without capturing a new recording.' It also routes to alternatives by naming the stop tools for data creation and the query tools for reading, and it specifies mode-specific requirements like session_id and device_id.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the prerequisite, failure condition ('Fails if native-profiler-analyze has not been run'), iOS-only restriction for leak_stacks, and return format (markdown report). It doesn't explicitly state read-only or side effects, but 'Query' and the failure discussion make it clear.

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?

Description is well-structured and front-loaded: prerequisite first, then bulleted modes, usage guidance, return type, and failure condition. Every sentence contributes meaningful information with no filler.

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 7-parameter tool with no annotations and no output schema, the description covers prerequisites, mode behavior, filters, output type, and error cases. It could be slightly more complete with an example invocation or more detail on the iterative workflow, but it is nearly sufficient for an agent to select and use the tool correctly.

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 description coverage is 100%, so the baseline is 3. The description reinforces mode semantics and adds small details (e.g., function_callers shows what a function calls, leak_stacks is iOS-only), but it does not significantly expand on the parameter schema, which already documents behavior.

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?

Description uses specific verb 'Query' with clear resource 'native profiler trace data' and enumerates four distinct modes with precise behaviors. It clearly distinguishes from sibling profiler tools by specifying that native-profiler-analyze must have been called first.

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?

Explicitly states prerequisite chain ('Requires native-profiler-stop → native-profiler-analyze') and gives a clear use case: 'Use when drilling into native hang stacks, thread CPU breakdown, or memory leaks after native-profiler-analyze.' However, it does not name alternatives or explicitly state when not to use this tool versus other profiler query tools.

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

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

No annotations are provided, so the description carries the full burden. It thoroughly discloses the return shape, the report's focus (hot commits ≥16ms with render cascades and root-cause identification), the side effect of saving raw data to disk for later profiler-load, the necessary preceding call, failure conditions, and the required post-report interaction (ask the user whether to drill down or fix and re-profile). The agent is fully informed of side effects and workflow constraints.

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 minimal but well-structured, progressing from purpose to return values, report structure, side effect, follow-up workflow, prerequisite, annotation guidance, usage condition, and failure mode. It is front-loaded with the core purpose. The slight redundancy is the annotation formula being repeated from the schema, but the additional sentences all carry meaningful context.

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?

With 6 parameters, no output schema, and no annotations, this description is remarkably complete. It covers the returned object, the report's content, the disk persistence side effect, the mandatory prerequisite, failure scenarios, and even the recommended next action after presentation. There is no critical gap that would prevent an agent from invoking the tool correctly.

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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explicitly restating the annotations parameter's computation formula (offsetMs = tapTimestampMs - startedAtEpochMs) and its intent (annotating commits with the user action that preceded them). This reinforcement helps the agent construct that parameter correctly, even though the schema already contains similar detail.

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+resource statement: 'Analyze stored profiling data and return a markdown performance report.' It clearly identifies the tool's role as the analysis step for profile data, and it distinguishes itself from siblings by referencing profiler-load for later reload and profiler-cpu-query / profiler-commit-query for drill-down. An agent can unambiguously determine this tool produces the main report.

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 makes the usage condition explicit: 'Use when the profiling session is complete and you need to interpret the collected data.' It adds a hard prerequisite ('Requires react-profiler-stop to have been called first'), describes the failure mode ('Fails if react-profiler-stop has not been called or no profiling data is stored'), and points to alternatives for follow-up actions (drill-down queries or re-profiling). This is a model of usage guidance.

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

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

Discloses key behaviors: returns found:false for node_modules components, handles multiple matches with otherMatches[], returns 50 lines of source and memoization status. No destructive actions mentioned; for a read tool this is sufficient.

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?

Only two sentences, front-loaded with primary function and output, then usage instruction and edge cases. Every sentence adds value; no waste.

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?

Despite no output schema, the description thoroughly covers return values (file path, line number, memoization, 50 lines of source, found status, otherMatches). Also explains the not-found case and ambiguity handling.

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 description adds context like component_name for lookup and project_root for file system. Also explains how parameters are used in the context of multiple matches.

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 uses a specific verb 'Find' and resource 'React component's source', listing exact return fields. It distinguishes itself from siblings like debugger-component-tree by stating its specific role in the profiling workflow.

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?

Explicitly says 'Call this per-finding after react-profiler-analyze to inspect source before proposing a fix.' Provides clear context but no explicit exclusion of alternatives.

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

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

With no annotations to supply safety or side-effect information, the description carries the full burden and does so well. It discloses that the tool reads from the stored cpuProfile, describes the output as a markdown table of top hotspot functions with specific columns, and states the failure conditions (react-profiler-stop not called or no stored profile).

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 purpose is front-loaded in the first sentence; the warning, alternative, use case, prerequisite, output format, and failure modes follow in tight, purposeful sentences. No sentence is redundant or purely administrative.

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 four parameters, no output schema, and no annotations, the description covers the essential context an agent needs: when to call it, what to call first, what it reads, what it returns, and when it fails. The markdown table columns are even specified, which compensates for the absent output schema.

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 description coverage is 100%, so the schema already explains all four parameters, including defaults and Chromium port behavior. The description reinforces the top-N concept but does not add meaning beyond the schema, which fits the baseline for fully documented 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 description opens with a clear verb and resource: 'Return a raw Hermes CPU flamegraph summary (top hotspot functions by self-time).' It explicitly contrasts itself with react-profiler-analyze and specifies its exact scope (JS CPU hotspots not tied to React rendering), so an agent can distinguish it from sibling profiler tools.

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?

It gives an explicit 'do NOT call' rule, names the sibling tool to use instead (react-profiler-analyze), and states the precise triggering condition ('JS CPU hotspots that are NOT tied to React rendering'). It also mandates the prerequisite call to react-profiler-stop, leaving no ambiguity about sequencing.

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

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

With no annotations, the description carries the full transparency burden and discloses meaningful behavior: the exact output shape (nested JSON with name, tag, actualDuration, selfBaseDuration, children) and the failure condition (missing React DevTools hook or no committed roots). It could have noted the implied requirement of an active debugger connection, but the key behavioral risks are covered.

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?

Four tightly scoped sentences: purpose, usage context, return format, and failure mode each in its own sentence. No filler, no repetition, and the most important purpose statement is front-loaded.