Roku Dev Studio MCP Server

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

The description goes beyond the annotations by explaining that the tool mutates session state, is idempotent with reconnection being a no-op, and that other tools auto-connect on demand. It adds useful behavioral context without contradicting the provided readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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 three tightly written sentences with no filler: it front-loads the purpose, then covers side effects and idempotency, then gives usage guidance. Every sentence contributes distinct information.

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 one-parameter connect tool with rich annotations and no output schema, the description covers purpose, side effects, idempotency, auto-connect behavior, and explicit usage conditions. An agent has enough context to decide when to call it and what it does.

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 provides full coverage for the single optional 'device' parameter, including the behavior of omitting it (uses the focused Dev Studio tab). The description does not add param-level details, but none are needed given the schema's completeness.

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 RALE / App Connector session against the device's running Dev App.' It clearly identifies what the tool does and implicitly distinguishes it from connection-disconnect and command-execution siblings such as app_connector_disconnect and rale_command.

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?

Usage guidance is explicit and practical: it says the tool is rarely needed because rale_command, app_function, and rale_get_node_by_id auto-connect on demand, and it states the only recommended uses are pre-warming the session or surfacing connection errors early. This gives clear when-to-use and when-not-to-use direction.

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 adds behavior beyond the annotations by stating "Mutates session state (tears down the connection)" and clarifying idempotence: "closing an already-closed session is a no-op." These details complement the idempotentHint and readOnlyHint annotations rather than merely repeating them.

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 three dense sentences with no filler. It front-loads the main action, then adds behavioral nuance, then gives usage context. Every sentence contributes distinct 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 simple one-optional-parameter tool, the description combined with the annotations covers the purpose, side effects, idempotence, and when to call it. 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?

The schema already documents the only parameter, device, with 100% coverage, including that it is optional and what happens if omitted. The description does not add further parameter-specific meaning, so the baseline score 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 opens with a specific verb and resource: "Close the RALE / App Connector session on the targeted device." This clearly distinguishes it from sibling connect/disconnect tools such as app_connector_connect and telnet_disconnect by naming the exact session type.

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 explicit triggers: "Use it to free the session or force a clean reconnect." It also provides useful when-not guidance: "normal RALE tools do not require you to disconnect between calls." However, it does not explicitly name alternative disconnect tools or state when to use telnet_disconnect instead, so it stops short of full routing 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?

Matches annotations by stating 'not read-only and not assumed idempotent' and 'may mutate app state'. Adds extra context: auto-connects the App Connector session and surfaces a toast in Dev Studio, which are not in annotations. No contradictions.

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

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

Every sentence serves a purpose – covering invocation, parameter format, backward compatibility, auto-connect, and side effects. Dense but not redundant; structure flows logically from usage to parameter details to 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?

Covers all aspects needed to use the tool correctly: when to use, parameter format, defaults, prerequisites, side effects, and auto-connect behavior. No output schema exists, so no return explanation required. Fully 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 description coverage is 100% and the description greatly enriches meaning: explains positional array format, zero-arg usage, named-object backward compatibility, normalization to positional, and the pitfall of key typos silently passing undefined. This goes far beyond the basic 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?

Clearly states 'Invoke a single function on the sideloaded channel through the App Connector' – a specific verb and resource. Distinguishes from siblings like list_app_connector_functions (lists) and app_connector_connect (connects).

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 this for any one-off function call' and contrasts with wrapping in an appFunction Action Script step for multi-step flows. Also instructs to always call list_app_connector_functions first, giving clear when-to-use 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?

Annotations already mark idempotentHint and openWorldHint, but the description adds crucial context beyond them: it is a no-op if already connected, it opens/focuses a tab with side effects, it will only connect reachable devices, and it never starts an rce emulator. This fully discloses behavioral traits that an agent must know to invoke and interpret the tool correctly.

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 carries operational value: purpose, idempotency, exclusions, alternatives, and device-specific preconditions. The most important information is front-loaded, and the structure makes the routing decision and failure conditions easy to follow.

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 single-parameter tool with rich annotations and no output schema, the description covers all invocation-relevant context: what happens on success, when it is unnecessary, idempotency, reachability requirements, and failure behavior. No critical operational gap remains for an agent selecting or calling 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?

Schema description coverage is 100%, and the input schema already defines `device` as a required non-empty string with LAN IP or serial examples. The description mostly restates that, adding only the source provenance ('from list_devices / scan_devices'), which is marginal value over 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 states a precise action: 'Open (or focus, if already open) a Dev Studio device tab for the given Roku' and clarifies the consequence of making it the active target for renderer-routed tools. It explicitly distinguishes the tool from direct-ECP alternatives like keypress and launch_app, so an agent can confidently tell it apart 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?

The description explicitly says when the tool is needed (for renderer-routed tools) and when it is not needed ('Not needed for main-direct ECP ops'), and it names test_connection as the alternative for reachability checks. It also gives per-device-type prerequisites (local discoverable, remote RDS Relay online, rce running), leaving no ambiguity about 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?

Annotations already declare readOnly and idempotent, and the description strengthens this by adding 'never touches the device' and 'analyzes the buffer Dev Studio already holds'. It also discloses the connection-dependent accumulation behavior and the recognition filter, which are operational traits not present in 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 long but densely informative, front-loading the core analysis action and then providing a complete return contract. Because there is no output schema, the detailed field documentation is necessary rather than redundant; every sentence adds operational 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?

Despite having no output schema, the description fully documents the return shape for both findings and crashes, including nested fields and semantics. It covers the connected=false edge case and the recognition limitations, leaving no critical operational gap for an agent to call 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% for the only parameter (optional device, omit for focused tab), so the schema fully documents parameters. The description does not add parameter-level meaning, so the baseline 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 verb and resource: 'Analyze the in-memory BrightScript debug console (port 8085) buffer and return the recognized BrightScript ISSUES and CRASHES'. It also delimits scope by stating it returns the same data the Console Monitor UI shows and excludes arbitrary app log output, which separates it from log-oriented sibling tools like get_telnet_log.

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 precondition and action: 'if connected is false call telnet_connect first', plus a clear exclusion ('NOT arbitrary app log output'). This tells an agent exactly when the tool is appropriate and what to do when the prerequisite is not met.

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?

Goes well beyond the annotations by explaining the idempotent no-op behavior when a healthy session exists, the teardown/reconnect only for missing/stale sessions, and the single-client control port rationale. This gives the agent a solid model of side effects without contradicting any annotation.

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 densely packed with actionable information, front-loaded with the required-first warning and the status-check shortcut. Every sentence earns its place by affecting whether or how the agent should invoke the tool.

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 side effects, the lack of an output schema, and the large sibling family, the description is complete: it covers prerequisites, safe reuse, failure conditions, teardown behavior, and the success return shape. Nothing critical 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 for the one optional parameter is 100%, and the schema already explains the device field's meaning and default behavior. The description adds little about the parameter beyond calling it a Roku, which is consistent but not a meaningful supplement.

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 opens a BrightScript debug session to the Roku on control port 8081. It also clearly marks itself as the required prerequisite for the debugger_* family, differentiating it from siblings like debugger_status and debugger_detach.

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 and when-not-to-use guidance: it says to call debugger_status first and skip attach entirely if already attached/running/stopped. It also explains the port-opening conditions and that attach returns an actionable error when the port isn't available.

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?

Annotations (readOnlyHint=false, openWorldHint=true) already indicate mutation and side effects, but the description adds specific behavior: execution resumes until breakpoint/STOP/error, and it only works from a halted state. This goes beyond annotation basics and gives the agent a concrete expected behavior. No contradiction with the 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?

Two sentences, front-loaded with the main action, then the follow-up and precondition. No filler or redundant phrasing. Every word contributes to the agent's understanding.

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, the description still tells the agent the immediate next step (use debugger_wait_for_stop) and the precondition (stopped). It does not mention the immediate return value, but the description implies the continue call doesn't provide the halt—so the follow-up is necessary. For a simple tool with one optional parameter, this is adequate.

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 device parameter is fully described in the schema, including its type, role (Roku IP or serial), and default behavior (omit to use focused tab). The description adds nothing about parameters. Since schema description coverage is 100%, the baseline of 3 is appropriate; there is no extra value from the description.

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 the specific verb 'resume execution' and the resource (debugger). It clarifies the condition under which execution runs (until next breakpoint/STOP/error). It does not explicitly contrast with siblings like debugger_pause or debugger_step, but the action is distinct enough that an agent can infer its purpose.

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 precondition: 'Only meaningful while `stopped`', which tells the agent when the tool should be used. It also names the follow-up tool debugger_wait_for_stop, guiding the agent on what to do next. It does not mention when to prefer it over debugger_pause/step, but the halted-state condition is a clear gating rule.

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?

Beyond annotations, the description discloses the side effect of releasing the 8081 socket and that the running channel continues executing. It also restates idempotency in operational terms ('no-op if not attached'), reinforcing the idempotentHint annotation. No contradiction with annotations exists.

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 compact sentences with no filler. The core action is front-loaded, and the key idempotency and execution-continuation details are packed efficiently into the remaining 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?

For a one-parameter tool with full schema coverage and informative annotations, the description covers the operation's side effects and no-op behavior. The lack of an output schema is not a concern at this complexity, though the description does not specify the return value on success.

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 single optional device parameter is fully described in the schema (IP/serial, must match a connected Dev Studio tab, omit for focused tab), so the description carries little parameter burden. The description only ties the session to a device generically. Baseline 3 for high schema coverage 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?

States a specific verb and resource: 'Close the debug session for a device', and adds the mechanism 'releases the 8081 control socket.' This clearly distinguishes it from sibling tools like debugger_attach and debugger_status by naming the exact action.

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: it is a teardown/cleanup operation, idempotent, and safe to call when not attached. It does not explicitly name an alternative such as debugger_attach, but the action is unambiguous enough for an agent to infer when to invoke it.

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 explicitly states that execution can have side effects and is not read-only, reinforcing the annotations (readOnlyHint=false, destructiveHint=true). It also adds useful behavioral context not present in the annotations: output streams to the device console, and compile/runtime errors are reported.

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, opening with the action, then giving examples, followed by the side-effect warning and alternative routing. Every sentence adds necessary information without 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, the description adequately covers the critical context: halted-frame requirement, side-effect warning, output destination, and error reporting. It leaves default behavior to the schema, which already documents threadIndex and stackFrameIndex defaults, so the overall context is 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 schema already documents all parameters. The description adds useful examples for the expression parameter and notes that stackFrameIndex/threadIndex select the scope, but this largely restates what the schema already provides.

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 identifies the operation as running a BrightScript expression/statement in the halted frame (the debug-console REPL), with concrete examples such as print m.top.count. This distinguishes it from read-only variable inspection tools like debugger_get_variables.

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 the core precondition that the target must be HALTED and explicitly routes plain variable reads to debugger_get_variables. It also warns that evaluation can have side effects, helping the agent decide when to use it versus safer 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral value beyond those: the halted-thread precondition, the top-frame-first ordering, and the default thread behavior. No contradiction with 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?

Three sentences with no wasted words. The primary return information is front-loaded, the required condition is stated immediately after, and the cross-tool usage note is compact and useful.

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 explains return shape, ordering, required precondition, and how the result connects to sibling tools, which is especially helpful given there is no output schema. It does not describe error behavior when the target is not halted, but the explicit HALTED requirement largely covers that 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 description coverage is 100%, so the baseline is 3. The description's threadIndex note repeats the schema's 'default the stopped/primary thread' almost verbatim)Skip, adding no new semantic value beyond the structured 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 names a specific verb ('Return') and resource ('call-stack frames') with concrete detail (function, file, line — top frame first). It is unambiguously distinct from sibling debugger tools and clearly scoped to the halted thread.

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 the key precondition ('Requires the target to be HALTED') and gives sequencing context by explaining that a returned frame index feeds stackFrameIndex into debugger_get_variables / debugger_evaluate. It does not enumerate exclusions or alternative tools, but no true alternative for call-stack retrieval exists among the siblings.

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?

Beyond the readOnly/idempotent annotations, the description discloses the response shape (name, type, value, childCount), the locals default when variablePath is omitted, case-sensitive AA lookup behavior, array indexing rules, and the [container].children drill-down result.

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 efficient: purpose and precondition first, then default behavior and return fields, then drill-down syntax and optional parameters. No filler or repetition.

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, the description supplies the essential return contract, including locals entries and container children. It covers defaults, path semantics, and the halted precondition; remaining details are either in the schema or not necessary 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?

Although schema coverage is already 100%, the description adds meaning: variablePath semantics (omitted default, quoted key vs bare number), stackFrameIndex default, and the shape of each returned variable. This materially enriches what the parameter schema alone provides.

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: 'Return variables in scope at a stack frame while HALTED.' It clearly focuses on variable inspection and drilling, which distinguishes it from sibling debugger tools like debugger_get_callstack or debugger_continue.

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 clearly states the precondition (HALTED) and explains how to use variablePath, stackFrameIndex, and threadIndex to choose a frame or drill into containers. It does not explicitly name alternatives such as debugger_evaluate, so it stops short of full when-not-to-use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds value by explaining the meaning of 'verified' (registered on the device) and 'queued' (waiting for the next halt to register), as well as the optional fields. It does not contradict annotations and provides useful behavioral context beyond the structured data.

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: the first states the action and resource, the second enumerates the return fields with inline clarifications for the less-obvious ones. No filler, no redundancy, and the key purpose is front-loaded. Appropriate length for the information delivered.

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, the description carries the burden of explaining the return shape, and it does so by listing each field with its meaning (verified, queued, optional fields). It covers the essential behavior of a read-only list tool; minor gaps like error cases or device-specific behavior are acceptable given the tool's simplicity and annotation coverage.

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% description coverage for the single optional 'device' parameter, fully explaining its semantics (Roku IP/serial, must match connected tab, omit for focused tab). The description adds no parameter-specific information, so 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 states a specific verb ('List') and resource ('breakpoints the debugger is tracking for a device'), clearly distinguishing it from sibling tools like debugger_set_breakpoints and debugger_remove_breakpoints. The field list further clarifies what is returned, leaving no ambiguity about the tool's function.

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 implies usage for inspecting breakpoints (read-only) but does not explicitly say when to use this tool versus alternatives like debugger_set_breakpoints or debugger_status. It does not mention when not to use it or any preconditions beyond the device parameter. Usage guidance is only implicit through the tool's name and read-only 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?

Annotations already mark readOnlyHint=false大手, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral nuance by stating the action is 'best-effort' and asynchronous, implying the halt is not guaranteed and that the actual snapshot comes from a subsequent call. This goes beyond what annotations provide.

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 two sentences with no filler. It front-loads the core action, then adds the essential follow-up and precondition. Every sentence contributes meaningful guidance, making it highly 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 simple, one-parameter tool with 100% schema coverage and no output schema, the description covers the core behavioral contract: request the halt, use wait_for_stop for the snapshot, and only invoke while running. It could theoretically state what the immediate response is, but that is minor given the clear workflow and the annotations already covering non-destructiveness and side effects.

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 single optional 'device' parameter is fully documented in the schema, including the fallback to the focused tab. The description itself does not add any additional parameter semantics or constraints beyond the schema, which warrants the baseline score 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 uses a specific verb ('Request a halt') with a clear resource ('a running channel') and adds the qualifier 'best-effort,' which precisely defines the action. It is clearly distinguishable from sibling tools like debugger_continue, debugger_step, and debugger_wait_for_stop, which represent different debugger control operations.

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 context: 'Only meaningful while running.' It also provides a follow-up workflow, instructing the agent to use debugger_wait_for_stop to get the snapshot once stopping occurs. It does not explicitly name alternatives or when-not-to-use scenarios beyond the 'only meaningful' condition, but the guidance is sufficient for correct 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?

Beyond the annotations (idempotentHint, readOnlyHint false, etc.), the description adds meaningful behavior: removal is by file:line and clears still-queued breakpoints without a device ID, and it returns '{ removed }'. This context is not present in structured data and helps the agent predict side effects 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?

Three sentences, zero fluff. The core action is front-loaded, followed by parameter semantics and return value. 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?

For a two-parameter tool with a fully documented schema and annotations, the description covers the essential operational behavior and output. The return value is stated, the input format is clarified, and the queued-breakpoint nuance removes ambiguity. Nothing critical 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 baseline is 3. The description adds value by explaining that the locations array must match debugger_list_breakpoints output and that removal by file:line also covers queued breakpoints, which is not obvious from the schema alone. This raises it to a 4.

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: 'Remove breakpoints by location.' It also clarifies that locations match what debugger_list_breakpoints reports, which distinguishes it from sibling tools like debugger_set_breakpoints and debugger_list_breakpoints. The purpose is immediately 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 gives clear context by specifying the locations format as matching debugger_list_breakpoints and notes the queued-breakpoint behavior, which guides the agent on when and how to invoke the tool. It does not explicitly name alternatives or when-not-to-use conditions, but the reference to list_breakpoints implies the correct input source and the tool name makes its role obvious.

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?

Beyond the annotations, the description discloses the pending/queued behavior when a breakpoint is added while the channel is running, the re-add replacement of existing conditions, and that each result returns a breakpointId or an error. This is meaningful operational detail the structured annotations do not provide.

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 action, then provides the parameter shape, then highlights the critical runtime behavior in a clear IMPORTANT clause. Each sentence serves a purpose and there is 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?

With no output schema, the description still explains what each result carries, covers the pending state, and describes re-add semantics. Combined with the schema's full parameter documentation, an agent has enough to call 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%, and the description largely restates what the schema already documents: path prefixing, condition as a BrightScript expression, and hitCount behavior. It adds little genuinely new parameter meaning beyond a compact summary, so the 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 opens with the exact action and resource: 'Add breakpoints.' It also names the data shape and the device context, and the sibling tools include debugger_remove_breakpoints and debugger_list_breakpoints, so the tool is immediately distinguishable as the write/set operation for breakpoints.

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 critical usage context: the device must be HALTED for breakpoints to register, and breakpoints added while running are queued with pending:true. It does not explicitly name alternatives like debugger_remove_breakpoints or debugger_list_breakpoints, but the use case is clear enough that an agent can select this tool confidently.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states the tool is non-blocking, explains the meaning of the 'stopped' state (HALTED — safe to inspect), and clarifies that a session may already be up from the app's own debugger UI. It doesn't describe polling frequency or error behavior, but the non-blocking disclosure is a meaningful addition.

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?

Three sentences, each earning its place: the first defines the return values and non-blocking behavior, the second gives a concrete pre-attach usage pattern, and the third routes to the blocking alternative. The most critical information (non-blocking, state values) 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 read-only status tool with one optional parameter, no output schema, and rich annotations, the description is complete. It covers what the tool returns, when to use it, how to interpret the key state, and which sibling to use for blocking behavior. Nothing an agent needs to call it 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 description coverage is 100%, so the schema already documents the single optional 'device' parameter. The description adds context about the parameter's purpose ('must match a connected Dev Studio tab') and the omit-to-use-focused-tab behavior, which is slightly beyond the schema. However, the schema already covers the core semantics, so the description's added value is marginal.

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 ('Return'), a specific resource ('session state for a device'), and enumerates all possible return values. It also distinguishes itself from debugger_wait_for_stop by explicitly noting it is non-blocking, which differentiates it from a sibling tool.

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 before debugger_attach to check if a session is already up, and poll to decide whether inspection tools will work. It also names the alternative (debugger_wait_for_stop) for blocking behavior, providing clear routing between siblings.

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?

Annotations already indicate the tool is not read-only (readOnlyHint=false) and not idempotent (idempotentHint=false), so the mutation behavior is implicit. The description adds the halted requirement and the fact that it moves execution, which is useful context beyond the annotations. However, it does not describe what happens if the thread is invalid or if stepping fails, leaving some behavioral gaps.

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 two sentences with no wasted words. The primary action is front-loaded, followed by the kind options, then the critical precondition and next-step guidance. Every clause serves a purpose, and the structure is logical and easy to parse.

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 moderate complexity (3 optional params, no output schema) and annotations that already cover mutation, the description is fairly complete. It provides the essential precondition, parameter semantics, and a follow-up for retrieving results. It lacks explicit error-handling details, but that is minor given that the schema covers all parameters and the annotations cover safety. An agent can call this tool correctly with the information provided.

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 significant value for the 'kind' parameter by explaining each enum value in plain language ('over' = next line skipping calls, 'in' = into the call, 'out' = finish current function), which goes beyond the schema's minimal 'Step kind (default "over").' The device and threadIndex parameters are adequately described in the schema, and the description does not repeat them.

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 ('Single-step the halted thread') with a specific verb and resource. It also enumerates the three step kinds, making the tool's function unambiguous. It distinguishes itself from siblings like debugger_continue and debugger_pause by focusing on single-stepping.

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 a critical prerequisite ('Requires the target to be HALTED') and provides a direct follow-up instruction ('Follow with debugger_wait_for_stop to get the new location'). This gives the agent clear guidance on when and how to use the tool, including a sequence that avoids wasted calls.

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 beyond the annotations: server-side blocking/polling, timeout handling with distinct return variants, and the exact state returned when the session ends. Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context without contradicting the 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?

Four sentences, each earning its place: core blocking behavior and return value, alternative timeout/session returns, when to call it, and timeout parameter details. The most important information is front-loaded, and there is 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?

There is no output schema, but the description fully supplies the return contract for all three outcomes: stopped, timed out, or session ended. It also covers invocation timing and the optional timeout parameter, making the tool complete and callable without further research.

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 both parameters, so the schema already documents device and timeoutMs. The description adds no new parameter-level meaning beyond restating the timeout default and cap, 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 states a specific action and resource: it blocks until the target halts at a breakpoint/STOP/step-completion/runtime error, then returns a structured stop snapshot. This clearly distinguishes it from sibling debugger tools like debugger_continue or debugger_status, which do different things.

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 tells the agent when to call this tool: right after debugger_continue, debugger_step, or after triggering the app. It doesn't explicitly state when not to use it or name alternatives, but the invocation context is clear and concrete.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation/side-effect profile is partially covered. The description adds valuable behavioral context beyond annotations: 'Changes device state (foregrounds the app on the requested content)' and notes that extra params are passed through to the channel. It doesn't detail failure modes or permission requirements, but the state-change disclosure is meaningful.

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?

Three sentences, all information-dense: the core action, the URL equivalence, the state-change warning, and the routing to the sibling. No filler or repetition of schema details.

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 5-param tool with no output schema, the description covers the core semantics, the state-change side effect, and the sibling distinction. It doesn't explain what the response looks like or what happens on failure, but the URL equivalence and param guidance give an agent enough to construct a correct call. The openWorldHint annotation also signals that extra params are allowed, which the description reinforces.

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 by explaining the relationship between contentId/mediaType and the URL equivalent ('Equivalent to /launch/<appId>?contentId=...&mediaType=...&<extra params>'), and by clarifying that params are channel-specific extras. This goes beyond the schema's individual 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 ('Launch an app straight into a specific piece of content'), names the mechanism (ECP Deep-Link with contentId + mediaType), and explicitly contrasts with the sibling launch_app ('to just open an app to its home screen use launch_app instead'). This clearly distinguishes it from the most similar sibling.

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 this when you have a content id to open; to just open an app to its home screen use launch_app instead.' It also mentions the alternative tool by name, which is exactly what an agent needs to select between the two.

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?

Annotations already declare destructiveHint and idempotentHint; the description adds human-readable detail that deletion when nothing is sideloaded still results in no Dev App, and notes the password-optional behavior tied to Dev Studio's memory. This adds context beyond the structured hints without contradicting them.

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?

Three sentences: first states the main action, second covers edge behavior and password, third routes to the alternative. No filler, front-loaded with the core operation.

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 destructive, idempotent two-parameter tool with no output schema, the description covers what is removed, the empty-state behavior, password handling, and the alternative install path. An agent has everything needed to 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?

Input schema provides 100% coverage with clear descriptions for both 'device' and 'password'; the description restates password optionality but does not add new meaning beyond the schema. Therefore the baseline 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 states a specific action ('Remove the currently sideloaded Dev App') and explicitly distinguishes it from the sibling 'sideload' by noting that sideload overwrites rather than requiring a delete first. This makes the tool's purpose immediately distinguishable from its closest alternative.

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 names the alternative tool (sideload) and the condition under which it should be used (install/replace), and clarifies that delete_sideload is not a prerequisite. Also explains when password is optional, giving the agent clear decision criteria.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: the quiet-failure mode when the feature was never enabled, uniform downsampling across the window rather than truncation, the `actualWindowSec`/`sampleCount` fallback when history is short, and the special single-value `cpuProcessSnapshot` that is not a historical series. This goes well beyond the annotations and helps the agent set 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 dense but every clause earns its place. It front-loads the core purpose and data source, then logically covers prerequisites, parameter effects, edge cases, and one special output. No filler or repeated schema information—only clarifying detail.

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?

There is no output schema, so the description must cover return shape and behavior. It does so thoroughly: compact per-timestamp entries, a decoding legend, `devicePerformanceEnabled`, `samples`, `actualWindowSec`, `sampleCount`, `downsampled`, and `cpuProcessSnapshot`. It also covers defaults, caps, and the only meaningful failure mode, making the tool fully invocable without additional lookups.

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?

Even though schema coverage is 100%, the description adds substantial meaning: it explains the per-sample key convention (`c`/`m`/`o`) and the role of `legend`, how `windowSec` interacts with retained history, how `maxSamples` causes even downsampling plus a `downsampled` flag, and why `cpuProcessSnapshot` appears only with cpu. This is significant value beyond the schema's parameter 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 and resource: it returns time-series device performance metrics for CPU, memory, and objects, tied to a known data source (chanperf/r2d2-bitmaps/app-object-counts). This clearly differentiates it from all sibling tools, which target debugging, networking, or app control, not performance telemetry.

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 and a concrete prerequisite: the 'Show Device Performance' quad layout must have been enabled earlier in the session, and the behavior when it was not is explicitly defined (empty samples, never an error). It does not name explicit alternatives or when-not-to-use versus a specific sibling, but the distinct purpose makes alternatives unnecessary.

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 annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the description's 'Side-effecting' statement mostly restates what the annotations provide. It adds the safety-focused guidance to prefer presets, but does not reveal additional behavioral details such as what state may change, auth requirements, or response 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 two concise sentences with no filler. It front-loads the core purpose, then immediately provides safety and alternative routing guidance.

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 raw, side-effecting POST tool, the description covers the key concerns: arbitrary endpoint, side effects, safe defaults, and read-only alternatives. It could mention what kind of response to expect, but given the arbitrary nature and lack of output schema, the description is sufficiently complete 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?

Schema description coverage is 100% and the endpoint parameter description already includes examples and the warning that arbitrary paths are sent verbatim. The tool description adds context about the endpoint being arbitrary, but does not materially enhance parameter understanding beyond the schema, so the 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 states a specific action ('POST to an arbitrary ECP endpoint') with a concrete example path and differentiates itself from sibling tools by naming list_post_presets and ecp_query. An agent immediately understands what this tool does and what it is not for.

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 agents when not to use this tool: use list_post_presets for safe defaults and ecp_query for read-only lookups. This is clear routing guidance that prevents unsafe or incorrect invocations.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description reinforces the read-only nature and adds behavioral context by listing example return categories and advising to use list_query_presets for endpoint discovery. It doesn't contradict annotations and provides additional context beyond the safety flags.

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 yet information-dense. The core action is front-loaded, followed by examples, endpoint guidance, explicit read-only note, and final routing to alternatives. Every sentence adds value with no filler or repetition, making it easy 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?

For a simple GET tool with 2 parameters and no output schema, the description covers purpose, usage, endpoint selection, alternatives, and the read-only guarantee. It's fully sufficient for an agent to decide when to call it and how to construct the request without additional lookup.

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 enriches meaning: it clarifies the endpoint parameter by specifying the two acceptable formats (preset names or /query/* paths) and provides a concrete usage example ('/query/apps'). This is beyond what the schema offers, making the tool easier to invoke 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?

States a specific verb ('Run') and resource ('read-only ECP GET'), lists concrete data examples (device info, installed apps, active app, media player state), and explicitly differentiates from the sibling ecp_post by mentioning state-changing POSTs. The agent can immediately tell what this tool does and how it differs from alternatives.

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 names when to use ('go-to inspection tool'), when not to (state-changing POSTs use ecp_post), and provides an actionable pattern: pick an endpoint from list_query_presets or pass any /query/* path. Also gives a concrete example for enumerating app ids ('/query/apps'). This is fully actionable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the result is an authoring schema scoped to one step type, but otherwise restates 'Read-only' and does not disclose error behavior for invalid types; the enum parameter largely mitigates that gap.

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 cover purpose, usage, alternative, and required argument with minimal waste. 'Read-only' and the parenthetical 'also enumerated in this tool's inputSchema' are slightly redundant with annotations and schema, but the description remains compact 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?

For a one-parameter read-only lookup tool, the description is fully adequate: it states what the return value is, when to call it, how it relates to siblings, and which argument is required. No output schema exists, but the description's mention of 'label, description, required and optional fields' covers the expected return content.

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 `type` parameter has an enum plus a descriptive comment, so the schema carries most of the semantic load. The description adds the cross-reference to list_action_types and clarifies that the argument is required, but it mostly reinforces what the schema already states.

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 opens with a specific verb and resource: 'Return the authoring schema ... for ONE Action Script step `type`'. It distinguishes itself from list_action_types (enumerates every type) and get_capability_bundle (whole contract at once), so an agent knows exactly what scope this tool covers.

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 explicit invocation context: call after list_action_types when authoring/fixing a specific step and needing exact field names before validate_script. Also names the alternative get_capability_bundle for the whole contract, so the agent can route between siblings without guessing.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context on top: the exact 336x210 dimensions, the ECP endpoint, the base64/data URL return format, and that the app must be installed. This is more than the minimal bar, though it doesn't describe error behavior for invalid app ids.

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?

Three concise sentences with the key facts front-loaded. The 'Read-only' phrase and the appId discovery sentence are slightly redundant with annotations and schema, but every sentence still adds useful invocation 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?

For a simple 2-parameter tool with no output schema, the description supplies the return format, dimensions, endpoint, valid-id discovery, and a clear alternative for a different use case. The optional device parameter is already fully documented in the 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?

Input schema coverage is 100%, so the baseline is 3. The description repeats the appId examples and the /query/apps source already present in the schema, and adds only the 'installed' qualifier. It doesn't materially extend the schema's parameter 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 uses a specific verb and resource: 'Fetch the 336x210 app icon for one installed channel' and specifies the return format (base64 / data URL). It distinguishes itself from the screenshot tool by stating that screenshot should be used for a picture of the current screen.

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 this tool ('to preview a channel's branding') and names the alternative for screen captures ('use screenshot instead'). It also tells the agent how to discover valid app ids via ecp_query /query/apps, which is practical guidance for invocation.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value beyond those by explaining the payload is static, that it should be loaded once and cached, and that the same JSON is exposed as a resource. No contradiction with 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?

Two sentences with no filler. The core purpose is front-loaded, the payload contents are enumerated compactly, and the usage directive ('load once, then cache') is placed immediately after the 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?

For a parameterless tool with no output schema, the description is complete: it identifies what is returned, enumerates its contents, states the expected usage pattern, and gives an alternative resource path. An agent has enough information to call it correctly and cache the 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?

The tool has zero parameters, so schema coverage is trivially 100% and the baseline is 4. The description adds meaningful context about what the returned payload contains, which is the closest analogue to parameter semantics for a parameterless tool.

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 verb and resource: it returns a single payload of every static capability, and it enumerates the major content categories (actions, vocabularies, RALE built-ins, presets, authoring rules, op directory, actionScriptAgentContract). This clearly distinguishes it from siblings like list_action_types or get_action_schema.

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: load once before authoring scripts, then cache. It also notes the same JSON is available as a resource URL, which helps an agent decide between fetching and using a cached resource. It doesn't contrast with specific sibling tools, but for a zero-parameter static bundle this 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that it returns empty/null when no tab is focused, which is valuable behavioral context not covered by annotations. It also reinforces the read-only nature without 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?

The description is concise, front-loaded with the main purpose, and includes key details without fluff. It efficiently covers return value, null case, read-only note, and usage guidance in a few sentences. Every 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?

For a zero-parameter read-only tool with clear annotations and no output schema, the description is complete. It explains what the tool returns, when to use it, and alternatives, which is all an agent needs to 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?

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining what the return value includes (ip, serial, etc.) and when it might be empty. However, it doesn't need to explain parameters since there are none, so a high score 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 clearly states the tool returns the focused device tab and lists example fields. It distinguishes itself from sibling tools list_devices (full inventory) and connect_device (change focus), making its purpose 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 call this tool: when resolving the implicit target for device ops when the user says 'this device' and gave no IP. It also provides alternatives: use list_devices for full inventory, connect_device to change focus. This is excellent 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?

The description goes beyond the readOnlyHint and idempotentHint annotations by explicitly stating the tool is read-only and never touches the device. It also reveals important behavioral traits: lines accumulate only while connected, and the tool drains an existing buffer, with a caveat about the single-client socket.

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, using about four sentences to cover the return shape, parameters, prerequisites, and caveats. Each sentence adds essential information without redundancy or unnecessary detail.

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 sibling tools include telnet_connect and console_monitor_findings, the description clearly places this tool in context by referencing the connection requirement and the buffer mechanism. It also describes the return structure, making it sufficiently complete even without an 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?

The schema covers 100% of parameters with descriptions, and the description further enriches semantics by explaining that afterCursor is from a previous call, omitting it returns the full buffer, and maxLines has a default and maximum. This provides complete context for each parameter's purpose.

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 lines from the BrightScript debug console buffer, specifies the resource (port 8085) and the return format, and distinguishes itself from sibling tools like telnet_connect and console_monitor_findings by focusing on reading the buffered output.

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 guidance: it is for polling (using afterCursor), explains how maxLines caps the response, and instructs to call telnet_connect first if the console is not connected. It also warns about the single-client limitation, giving clear conditions for correct use.

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?

Annotations already flag readOnlyHint=false and idempotentHint=false; the description goes beyond those flags by explaining the mechanism — repeated calls append to the focused field — which is precisely the behavioral nuance structured hints cannot convey. The focus prerequisite is also a real runtime condition worth stating. Minor omission: the failure mode when no field is focused is not described.

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 with a distinct job: core action, precondition, mutation semantics, and alternative routing. No filler or repetition of schema content, and the most decision-relevant facts are front-loaded in the first 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?

For a two-parameter tool with no output schema, the description covers the action, the focus precondition, the append/mutation behavior, and when to choose it over keypress. The only gap is error behavior (e.g., what happens if nothing is focused or input is rejected), which is a minor omission for a simple input-send 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 both text and device are already documented with examples and default behavior. The description adds only the 'literal' nuance to the text parameter, which is marginal beyond the schema's 'Text to send.' The baseline 3 for high schema coverage 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 verb and resource — 'Type a literal text string into whatever input field is currently focused on the device' — anchored to the ECP /input endpoint. It also preemptively distinguishes itself from keypress, its nearest sibling, so an agent can route correctly without opening the schema. The domain is completely 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 precondition is stated explicitly ('Requires a text field to already be focused'), the alternative tool to satisfy it is named ('use keypress to navigate into one first'), and the substitution rule is given ('Use this instead of sending characters as individual keypress keys'). Both when-to-use and when-not-to-use are covered with zero inference required.

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 goes beyond the annotations by explicitly stating that each key advances the UI and repeated calls are not a no-op, which aligns with idempotentHint=false. It also conveys the side-effect profile ('mutates on-screen state') beyond what the annotations alone imply.

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?

Three sentences with no filler: the core action, the behavioral caution, and the routing alternative are each compact and front-loaded. Every sentence contributes to correct usage.

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 two-parameter tool with full schema coverage and no output schema, the description is complete. It explains what the tool does, its side effect profile, and how to choose it versus the closest sibling, leaving no critical 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%, and the schema already documents the key enum and device semantics. The description adds examples of valid keys but does not materially extend meaning beyond the schema, matching the baseline for high 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?

Description states a specific verb-resource pair: send one ECP remote key to a Roku device, with concrete examples. It is clearly distinguished from sibling tools like input_text and ecp_post by describing its exact role as a remote-press mirror.

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 names the alternative input_text and gives the condition for choosing it ('to type characters into a focused text field'), while reserving keypress for navigation/transport keys. This is direct when-not guidance that enables correct 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?

The description goes beyond the annotations by stating 'Changes device state (foregrounds the app)', which clarifies the real-world side effect. It also reveals that optional launch params are passed through as ECP query params, adding behavioral detail that annotations alone do not provide.

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: the core action is stated first, followed by id discovery, side effect, alternative, and params. Each sentence earns its place with no redundant 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?

Given the lack of an output schema, the description still fully covers what an agent needs: what the tool does, how to get valid appId values, the state-change behavior, the sibling alternative, and how params are handled. Nothing critical for correct invocation 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 description adds semantic value by explaining how to discover appId values via ecp_query and that params are passed through as ECP query params, which goes beyond the schema's bare 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 clearly states the verb 'Launch' and the resource 'channel / app on the device to its home screen by app id.' It also distinguishes this from the sibling deep_link by explicitly noting deep_link opens a specific title, making the tool's purpose 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 explains how to discover app ids via ecp_query "/query/apps", notes the special 'dev' id for sideloaded apps, and provides a clear alternative: use deep_link when opening a specific title. This gives the agent concrete decision criteria.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 'Read-only' (redundant) but also contextual behavior like 'Start here' which frames the tool as a non-mutating entry point. It doesn't contradict annotations and adds mild workflow context, so a 4 is appropriate given the lower bar set by the 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?

Three sentences, front-loaded with the core purpose, then a concise workflow sequence, then an alternative. Every sentence serves a function: stating output, giving usage order, and offering a fallback. No fluff, and the structure is easy to scan.

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

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

For a zero-parameter, read-only, idempotent tool with no output schema, the description provides everything needed: what it returns, the recommended order of operations, and alternatives. It's complete for an agent to invoke it correctly without further investigation.

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 the schema has no properties. Baseline for 0 params is 4. The description doesn't need to explain any parameters, and the schema is fully covered. Nothing is missing.

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: 'Return every supported Action Script step type' with metadata like label, description, and fields. It clearly distinguishes this from siblings by naming the exact next step (get_action_schema) and positioning itself as the entry point. An agent can immediately understand what this tool does and why it exists.

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 'Start here when authoring a script' and provides a recommended sequence: call get_action_schema for one type, then validate_script before send_script_to_builder. It also offers an alternative for a full contract (get_capability_bundle or a resource URI). This gives unambiguous when-to-use guidance and 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by explaining the output structure (name, params array, optional description) and instructs to surface the description verbatim to the user, which is behavioral guidance beyond the annotations. It does not contradict 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 multi-sentence but each clause earns its place: the source, the output shape, the verbatim-handling instruction, the usage timing, and the parameter. It is front-loaded with the core purpose and efficiently packed. No redundancy 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?

Without an output schema, the description compensates by detailing the return structure (name, params, optional description) and the source. It also explains the usage relationship with appFunction. Given the tool is simple and annotations cover safety, this is sufficiently complete for an agent 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% and the device parameter is described in the schema as 'Optional. Roku IP or serial; must match a connected Dev Studio tab when set.' The description simply restates 'Optional device (IP or serial)' without adding new meaning. Baseline 3 applies since the schema already carries the full 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 states a specific verb and resource: it lists app connector functions, sourced from RALE getExternalControlFunctions. It clearly distinguishes itself from sibling tools by focusing on function metadata for appFunction authoring, and names the sibling appFunction as the downstream consumer. 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?

The description explicitly says 'Call before authoring appFunction steps so names and param keys/order match', giving a concrete trigger condition. It also notes the optional device parameter, providing context for when to include it. This directly guides the agent on when to invoke this tool relative to appFunction.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the meaning of isTabOpen vs isReachable, the source field semantics (local/remote/rce), the fact that rce devices have no real IP, and the caveat that sideload/delete_sideload don't work against rce devices. It also discloses that other tools will fail with a clear 'not responding' error, which sets expectations for downstream behavior. It doesn't describe pagination or ordering, but for a zero-parameter list tool this is minor.

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 covers scope, field semantics, source types, usage guidance, and sibling differentiation. It is front-loaded with the core purpose and read-only nature, then expands into necessary caveats. It could be slightly tightened, but the density of useful information justifies the length.

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 zero-parameter, read-only list tool with no output schema, the description is remarkably complete. It explains the return fields, the meaning of each source type, the isReachable caveat, how to use it as a first step, and how it relates to siblings. An agent has everything it needs to call this tool correctly and interpret its results.

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% (empty object), so there are no parameter semantics to document. The description compensates by thoroughly explaining the return fields and their meanings, which is the closest equivalent to parameter semantics for a no-input tool. Baseline 4 is appropriate for a zero-parameter tool.

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 ('Return every device Dev Studio already knows about') and immediately distinguishes itself from scanning by stating 'without running a network scan.' It enumerates the exact fields returned and explicitly contrasts itself with related tools (get_selected_device, scan_devices, connect_device), so an agent can tell it apart from siblings 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?

The description explicitly says to use this as the first step to resolve a `device` argument for other tools, and names the alternatives with their conditions: get_selected_device for the one focused device, scan_devices for actively probing new devices, connect_device for opening/focusing a tab. It also gives behavioral guidance on how to interpret isReachable and when to tell the user to check the device rather than retrying.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds a meaningful behavioral prerequisite ('Requires Network Inspector enabled') and clarifies that the tool aggregates existing captured data rather than capturing new data ('Aggregate the captured buffer'). This goes beyond the annotations without contradicting them.

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 starts with the core action and output list, then the use case, then the shared filter reference, then the requirement. Three sentences, no filler, and every sentence contributes actionable information for tool selection and invocations.

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, the description takes on the burden of describing what the tool returns, and it does so concretely by listing the aggregations (counts by event type, status class, top hosts, content types, transaction totals, error counts, largest responses). It also mentions the enabled prerequisite and the accepted filters. It does not explain the shape of 'hotspots' or pagination, but for an aggregate summary tool this is a minor omission given the output list provided.

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 already fully documented in the input schema. The description adds only that these are 'the same optional filters as network_inspector_list_events', which gives a useful cross-tool consistency hint but does not explain individual parameter semantics beyond the schema. Baseline 3 is appropriate, as the schema carries the 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 and resource: 'Aggregate the captured buffer into hotspots and rollups in one call' and enumerates the exact computed outputs (counts by event type, HTTP status class, top hosts, content types, etc.). It further distinguishes itself from siblings by stating its intended position in a workflow: 'Use this to orient on a session before drilling into individual events.' An agent can immediately tell this is the aggregation/summary tool, not a list/detail tool.

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

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

The description clearly states when to use the tool ('orient on a session before drilling into individual events') and names the sibling whose filters it mirrors (network_inspector_list_events). It also adds a prerequisite ('Requires Network Inspector enabled'). However, it does not explicitly name an alternative for the drill-down step or state a 'when not to use' condition, so it stops just short of fully explicit when/when-not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds valuable behavioral details: the result structure (total, scopes, summary), the safe degradation of dangerous/over-long regex patterns to a literal search, and the prerequisite that Network Inspector must be enabled. This goes well beyond the annotations and gives the agent a complete picture of expected 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 a single, well-organized paragraph with zero filler. The main purpose is front-loaded, followed by usage distinction, result structure, parameter details, and a prerequisite. Every sentence carries essential information, and the structure makes it easy to scan for the key facts.

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 (6 parameters, 1 required, no output schema), the description is exceptionally complete. It covers the tool's purpose, when to use it, all parameters with their defaults and interactions, the result structure, and a prerequisite. Nothing an agent needs to call it correctly is missing, and it even explains edge-case behavior (regex degradation).

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 each parameter described, but the description adds semantic context beyond the schema: it explains that scopes can be omitted to search all parts, that regex treats query as a JS regex with graceful degradation, that device defaults to all Rokus, and that limit caps results. It also clarifies the meaning of the result's scopes breakdown, which is not in the schema. This fully compensates for any gaps and enhances parameter understanding.

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 ('Search') and a well-defined resource ('FULL content of captured transactions' including URL, headers, bodies), and explicitly contrasts with sibling network_inspector_list_events' host filter. This makes the tool's purpose unmistakable and differentiates it from alternatives.

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 this is the tool for 'which request(s) contain X' across the whole buffer, and contrasts with using network_inspector_list_events for host-only filtering. It also names an alternative (get_event_detail) and mentions the prerequisite that Network Inspector must be enabled, providing clear when-to-use and when-not-to-use 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds meaningful context beyond them: what is returned, the proxy trust purpose, and the practical effect of making HTTPS bodies visible. It also notes the 'sideloaded dev channel' prerequisite without contradicting the 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?

Two sentences, with returned items front-loaded and the use case following immediately. Every clause adds useful information; there is no filler, tautology, or restatement.

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 parameterless, read-only, idempotent helper, the description fully covers what the agent needs: what the tool returns, why it is useful, and exactly when to call it. The named return items are sufficiently clear even without an 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?

The schema has zero parameters and schema_description_coverage is 100%, so there is nothing for the description to compensate for. The description appropriately reinforces that only fixed, parameterless information is returned.

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: 'Return the Dev Studio MITM CA fingerprint, proxy host:port, and the BrightScript snippet.' This clearly distinguishes it from sibling network_inspector tools, and the reference to network_inspector_list_events establishes how it fits in the broader 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?

It gives an explicit trigger: 'Use when network_inspector_list_events shows TLS handshakes but no decrypted HTTP bodies.' This clearly identifies the situation and user goal, though it does not enumerate when-not-to-use conditions or explicitly name alternative 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?

Adds significant behavior beyond annotations: truncation at maxBodyChars, warnings when truncated, use of includeFullBody to override, and the no-body/404 edge case for DNS/TLS/TCP events. This is consistent with readOnly, idempotent, and destructiveHint false 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?

Three sentences, front-loaded with the core purpose and id provenance, followed by behavior caveats and prerequisite. Every sentence contributes actionable 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?

Covers the critical edge cases, prerequisites, truncation, override, and possible 404. It does not fully describe the response envelope beyond 'headers and body' and 'warnings', and there is no output schema, but the description is strong enough for an agent to call it correctly in most cases.

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 meaning by tying id to list_events output, providing the default 4096 cap, warning that includeFullBody can return very large data, and explaining per-event body constraints.

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 verb ('Fetch'), a clear resource ('full headers and body for one captured event'), and the id source ('from network_inspector_list_events'). This distinguishes it from list_events and other network inspector sibling tools without ambiguity.

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 concrete context: use with an id from network_inspector_list_events, requires Network Inspector enabled, and warns that DNS/TLS/TCP events may yield 404. It does not explicitly contrast with alternative sibling tools, but the id-source instruction and clear purpose make appropriate use obvious.

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?

Beyond the annotations' readOnly/idempotent hints, the description adds genuinely useful behavioral context: 'Summary-first by design to protect context' (explains the deliberately truncated output), 'Returns most-recent events' (ordering contract), AND/OR filter combinatorics, and the prerequisite state dependency. No contradiction with the annotations exists.

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 well-ordered: purpose, drill-down pointer, design rationale, filter semantics, ordering, prerequisite. The long parameter glossary is justified by 10 parameters, though it partially restates schema content and could be tightened by trimming redundant per-field phrasing.

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 10-parameter, no-output-schema read tool, the description covers prerequisites, filtering semantics, defaults, ordering, and drill-down routing. The one gap is that it tells the agent what summaries lack ('no full headers/body') but never what fields they contain, leaving the return shape to 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?

Although schema coverage is 100%, the description adds meaning the schema lacks: cross-field AND-combination with OR-within-arrays, the errorsOnly shortcut mapping to statusClass 4xx+5xx, the device omit-for-all-Rokus semantics, and the limit default/max. These semantics materially change how an agent composes a correct call and go well beyond the per-field 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 ('List captured network events as lightweight summaries') and adds a scope qualifier ('no full headers/body'), then explicitly names the sibling it is not (network_inspector_get_event_detail). An agent can distinguish this tool from the other network_inspector_* siblings without opening the schema.

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

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

It gives explicit routing to network_inspector_get_event_detail for drill-down and states the prerequisite ('Requires Network Inspector enabled (see network_inspector_status)'). It does not, however, address the overlapping siblings network_inspector_find and network_inspector_analyze, leaving some ambiguity about when those should be preferred, so it falls just short of full when/not-when coverage.

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?

Annotations already signal readOnly/openWorld/idempotent/non-destructive. The description adds important behavioral context beyond those hints: the gating 'ready' condition, the need to relay notice/remediation when not ready, and the fact that reads return nothing useful until ready is true.

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 well-structured sentences front-load the purpose and then give actionable gating instructions. The slight repetition that reads are not useful until ready is true reinforces a critical operational constraint rather than being 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?

With no output schema, the description enumerates the key status dimensions an agent needs: ready state, connected clients, packet/event counts, MITM state, and prerequisites remediation. It also gives the conditional workflow for acting on ready=false, making the tool fully understandable for a zero-parameter status probe.

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 accepts zero parameters, and the schema covers 100% of them trivially. With no parameters, the description has no parameter meaning to add and instead focuses on status output semantics, which is the appropriate 0-parameter baseline 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?

States a specific verb-resource pair ('Report whether Dev Studio's Network Inspector is enabled') and enumerates what it covers: Roku clients, packet/event counts, MITM state, and prerequisites remediation. It also differentiates itself by explicitly instructing 'Call this first' before other network_inspector_* 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?

Gives an explicit usage directive: 'Call this first before the other network_inspector_* tools'. It also tells the agent exactly how to behave when ready is false (relay notice/remediation) and clarifies that reads are not useful until ready is true.

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 annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: the session-level contract, the 'call once before first bridge-dependent tool' rule, and the `live:false` failure shape with a reason field. This is meaningful supplementary detail rather than a restatement of 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 a single, focused sentence with the return contract front-loaded and the usage rule immediately after. Every clause contributes either to what the tool returns or when to call it. There is no filler or repetition of schema or annotation data.

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 zero-parameter, no-output-schema status probe, the description fully equips an agent to invoke it correctly: it explains the return shape, the failure case, and the session-level usage policy. It even names the sibling operations that depend on a successful probe. 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter meaning the description needs to add. The baseline for a no-parameter tool is 4, and the description appropriately focuses on return-value semantics instead. No parameter-related gap exists.

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 defines the tool as a bridge liveness probe by specifying the exact return shape: `{ live, port, pid, startedAt }` or `{ live: false, reason }`. It distinguishes itself from sibling status tools like `debugger_status` or `test_connection` by framing itself as a one-time precondition for bridge-dependent operations. It lacks an explicit verb phrase like 'checks whether', but the return contract makes the purpose 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 gives an explicit usage rule: call once per session before the first bridge-dependent tool. It also states when re-probing is unnecessary once `live=true`, and it names the affected direct operations such as keypress, launch_app, ecp_query, rale_command, and send_script_to_builder. This is strong, actionable guidance for an agent deciding when 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds value beyond them: every call surfaces as a toast in Dev Studio, the mixed read/write nature is spelled out ('the tool as a whole is not read-only'), and concrete destructive command examples are given. No contradiction with annotations; the description reinforces and extends them.

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 with no wasted words: purpose and destructive scope are front-loaded, followed by catalog pointer, toast behavior, and read/write routing advice. Every sentence earns its place and the structure moves from most critical (what it does) to supporting detail.

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 high-complexity dispatch tool with open-world semantics, no output schema, and a dynamic args object, the description provides strong coverage: destructive warning, catalog discovery path, side-effect visibility (toast), and sibling routing. It could note that output shape varies by command or describe error behavior, but the list_rale_builtins pointer substantially mitigates that gap for a generic runner.

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 three parameters including the shape-dependent args object. The description adds a few illustrative command names (getNodeById, getRegistry, clearRegistry) and points to the args template in list_rale_builtins, but it doesn't add substantive parameter semantics beyond the schema — 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 opens with a specific verb and resource ('Run any built-in RALE command against the active App Connector session') and explicitly flags destructive capability. It differentiates from siblings by naming rale_get_node_by_id as the plain-read alternative and list_rale_builtins as the catalog source, so an agent can select it correctly 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?

The description gives clear context: use this for any built-in command including destructive ones, consult list_rale_builtins for the catalog, and prefer rale_get_node_by_id for plain reads. It names an explicit exclusion (plain reads) and the alternative, though it doesn't enumerate when-not-to-use cases beyond reads or address overlap with other write-capable siblings.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: it requires a connected App Connector session, can auto-connect, and fetches node fields/children from the running Dev App. It does not mention return format or error behavior, but annotations lower the burden here.

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, then adds usage guidance and parameter semantics in a structured way. Every sentence carries necessary information with no fluff or repetition of schema details.

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 read-only fetch tool with three well-documented parameters and strong annotations, the description is complete. It covers the tool's purpose, connection requirements, when to use it versus rale_command, and enough parameter semantics for correct invocation. The expected result (node fields/children) is also 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?

Schema coverage is 100%, so each parameter is already documented. The description adds meaningful clarifications beyond the schema: id is the authored XML/BrightScript id, path is for disambiguation when id is not globally unique, and device can be an IP/serial or omitted for the focused tab. These details help the agent invoke parameters 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 clearly states the tool fetches one SceneGraph node by id and identifies it as a read-only convenience wrapper over rale_command getNodeById. It names the exact resource and operation, and differentiates it from the general rale_command sibling.

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 this tool ('common inspect one node' case), when not to use it, and directs the agent to rale_command for other RALE built-ins. It also states the connectivity requirement and that the tool auto-connects if needed, leaving no ambiguity about prerequisites.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by clarifying that the tool 'does not connect devices' and explaining the network scan nature, which is relevant context beyond the structured hints. No contradictions.

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 with zero waste. The purpose is front-loaded, the scope is stated, and the sibling distinction is given in the second sentence. Every word contributes to agent decision-making.

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 simple with two optional parameters and no output schema, but the description covers purpose, side effects (none destructive), usage alternatives, and follow-up actions. The return value (discovered devices) is implicitly clear from 'Discover Roku devices'. An agent has all necessary information 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 description coverage is 100%, meaning both parameters (timeoutMs and includeSubnetScan) are already well-documented in the schema. The description mentions SSDP and subnet HTTP sweep, which loosely maps to the parameters, but it does not add meaningful detail beyond what the schema provides. 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 verb 'Discover' with the resource 'Roku devices on the local network' and specifies the method (SSDP multicast and optional HTTP sweep). It explicitly distinguishes itself from siblings by naming connect_device (for opening a tab) and list_devices (for known devices), so an agent can unambiguously select the right tool.

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 when-to-use and when-not-to-use guidance: 'Use this to FIND unknown devices' and directs to list_devices for already-known devices. It also notes the follow-up action with connect_device, giving a clear workflow. No inference is required.

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?

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds the return behavior: inline image when true, and a JSON object with { success, filename, bytes } when false, plus the note that hosts render the image. It also discloses password optionality. This goes beyond the annotations without contradicting them, though it doesn't mention any side effects (none expected given idempotence).

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 four sentences, each with a purpose: core action, host rendering context, parameter usage guidance, and password note. It is front-loaded with the primary behavior and then provides conditional details. Slightly longer than necessary but every sentence adds value, so it earns a 4.

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 4 parameters, no output schema, and annotations present, the description explains the return format in both modes, when to use the boolean, and password handling. It does not cover error cases or what happens if the device is unspecified, but those are covered by schema and the focused-device concept. The description is sufficient 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for `returnImageBase64` (when to set false) and clarifies password behavior ('optional when Dev Studio has remembered it'), which reinforces the schema. For `device` and `waitAfterTriggerMs`, the schema already explains them, so the description adds no extra value there, but the added emphasis on the boolean is valuable.

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 ('Capture a screenshot of the current device screen') and the resource (the device screen). It also specifies the return format ('inline as an MCP image content block (JPEG, base64)'), which distinguishes it from other tools. No sibling performs the same function, so differentiation is inherent, but the description is precise 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 gives explicit guidance on when to use the `returnImageBase64` parameter: 'for any human-facing capture let returnImageBase64 default to true (or omit it)' and 'Set returnImageBase64: false ONLY for batch / metadata-only flows'. It also notes the password is optional when remembered, covering usage prerequisites. This is clear, actionable usage direction.

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?

Annotations already give readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it does not auto-run, performs the same validation as validate_script, and is intended for human review. While it could clarify what happens after validation (e.g., what 'sending to builder' changes in the UI), the added behavioral info is significant.

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 key behavioral fact, then covers arguments, then gives decisive usage routing. Every sentence adds value, and the guidance is compact despite covering both when-to-use and when-not-to-use.

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 enough for a moderately complex tool with 2 parameters, no output schema, and decent annotations. It covers what the tool does, its validation behavior, parameter types, and the exact conditions for use versus direct alternatives. A minor gap is that it assumes the agent understands what 'Dev Studio Builder' is and what 'human review' entails, but for the intended audience this is 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%: both `script` and `device` are already documented in the schema with shape and constraints. The description repeats the argument names and basic types, but does not add meaning beyond the schema, except for referencing validate_script's script shape, which the schema itself already mentions. 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 states a clear specific action: sending a validated Action Script into Dev Studio Builder for human review, and explicitly distinguishes it from validate_script and direct operations. The verb 'drop' is informal but unambiguous, and the resource ('Dev Studio Builder') and behavior ('does not auto-run') are concrete.

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 the tool: only for multi-step, conditional, or saved/reviewed flows. It also provides clear when-not-to-use guidance by listing direct operations like keypress, launch_app, rale_command, ecp_query, and screenshot for single deterministic actions. This is exemplary 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?

Annotations already include destructiveHint: true and readOnlyHint: false, but the description adds specific behavioral detail: it replaces the currently sideloaded Dev App, writes base64 content to a temp file, sideloads, then cleans upaint. This meaningfully exceeds the structured annotation hints.

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 its length is justified by two mutually exclusive input modes and a meaningful destructive warning. The flow is logical: core purpose, destructive warning, filePath pathway, contentBase64 pathway, then password nuance. Every sentence earns its place, though it could be trimmed slightly 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?

The tool has no output schema)Skip, but the description covers prerequisites, both input modes, cleanup behavior, destructive effects, and edge-case path failures. It omits what the success response looks like, which an agent might want, but the invocation guidance is thorough enough that this 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 description coverage is 100%, so the baseline is 3. The description adds beyond the schema by explaining the real-world constraint that filePath only works on the same machine as Roku Dev Studio)Skip, and by giving a decision rule for choosing contentBase64 over filePath. This adds semantic value, but some sentences mostly restate 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: 'Upload and install a .zip channel package on the device.' It further distinguishes the operation by noting it replaces the currently sideloaded Dev App, which separates it from sibling tools like delete_sideload or 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 explicitly says when not to use this tool ('Do NOT use this when running in a remote agent sandbox') and when to use it ('Use this whenever the agent has file content but no shared filesystem'). It also warns that the operation is destructive and not safe for autonomous use without user intent, giving clear usage boundaries.

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 explicitly discloses side effects ('Opening the socket is a side effect (displaces other clients), so this is not read-only'), which reinforces the readOnlyHint=false annotation. It also details the idempotent return shape and the requirement to call before logs accumulate, adding behavioral context beyond the 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 dense but efficient. It front-loads the core purpose, then covers idempotency, sequencing, and side effects in a logical order. Every sentence adds necessary information without redundancy, achieving high information density without verbosity.

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 connection tool with no output schema. It explains the return value for the idempotent case, the subsequent polling step, and the side effect of displacing other clients. Given the tool's complexity and the lack of an output schema, the description covers all the agent needs to know 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?

The input schema already describes the optional 'device' parameter with a clear description ('Optional target device (IP or serial). Omit to use the focused tab.'). The description does not add further semantic detail about the parameter beyond what the schema provides, so the baseline 3 applies with 100% 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 states the exact verb and resource: 'Open the BrightScript debug console (TCP 8085) for the targeted device', explicitly likening it to the Connect button. It distinguishes from siblings like telnet_disconnect and get_telnet_log by its role and sequencing.

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: it must be called before lines accumulate, and after successful return the agent should poll with get_telnet_log. It also warns about the single-client nature that can displace other clients, implying when to avoid use (e.g., if another session is needed) and clarifies idempotent behavior.

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?

Annotations already indicate readOnlyHint=false and idempotentHint=true. The description adds valuable details: the exact idempotent return value `{ connected: false, already: true }` when no session is open, and explicitly warns that closing the socket is a side effect, reinforcing that it is not read-only. This goes beyond the annotations and fully discloses 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 concise (three sentences), front-loaded with the primary action, and includes essential details like idempotency and side effects without any fluff. 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?

For a simple tool with one optional parameter and no output schema, the description covers everything an agent needs: the action, the idempotent behavior with a specific return value, the use cases, and the side-effect warning. The annotations complement it well, and 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 description coverage is 100% since the only parameter 'device' has a clear description in the schema ('Optional target device (IP or serial). Omit to use the focused tab.'). The tool description does not add any additional meaning beyond the schema, so the baseline 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 clearly states the specific verb 'Close' and the resource 'BrightScript debug console (TCP 8085)', and it explicitly mirrors the Disconnect button. It distinguishes itself from siblings like telnet_connect (opposite operation) and get_telnet_log (reading logs) by specifying the exact scope.

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 use cases: 'Use this to release the 8085 socket so another tool can attach, or to stop log accumulation.' It clearly implies when to use it, though it does not explicitly name alternative tools or state when not to use it. The context is sufficient for an agent to decide.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: no Dev Studio tab requirement and that it verifies a single known address. This goes beyond the annotations without contradicting them.

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?

Three sentences, each earning its place: purpose, a key usage condition, and sibling differentiation. Front-loaded with the core action, 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?

Complete for a simple read-only probe with one optional parameter. The description covers what it does, when to use it, how it differs from siblings, and the safety profile is already in annotations. No critical information 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 sole parameter 'device' is fully described in the schema (IP or serial, optional, with fallback to focused device). The description does not add new parameter semantics, but schema coverage is 100%, so baseline 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?

States a specific verb ('Probe'), a clear resource ('one known device IP for ECP reachability'), and the output ('return basic device info'). It explicitly contrasts with siblings probe_bridge and scan_devices, making its purpose 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?

Gives explicit when-to-use: 'confirm a specific IP is a reachable Roku before connect_device.' It also clarifies it does not require a Dev Studio tab, and directly names alternatives with their different purposes, so the agent knows exactly when to pick this tool over siblings.

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?

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: the response structure, that ok=false is surfaced as isError, and the reference to an external contract resource. This goes beyond the annotations without contradicting them.

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 information-dense. It front-loads the purpose, then covers the parameter, response contract, error behavior, and usage boundaries in a few sentences with no filler or redundant elaboration.

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, the description fully explains the response fields and error semantics. Combined with the single well-documented parameter and the explicit usage guidance, the agent has everything needed to invoke and interpret 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?

The input schema already provides 100% parameter coverage with detailed explanation of the script object's minimum shape and the two acceptable formats. The description only briefly restates 'script: JSON object or JSON string', adding little beyond the schema. 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 states a specific verb and resource: 'Validate an Action Script before send_script_to_builder'. It clearly differentiates validation from the subsequent build/send step and from the direct operations listed as alternatives.

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 tells when to use this tool ('before send_script_to_builder') and when not to: for single actions, use direct operations like keypress, launch_app, rale_command, ecp_query, ecp_post, screenshot. It also specifies the flow types that warrant a script: multi-step, conditional, polling, or saved-or-reviewed.

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