Roku Dev Studio MCP Server

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

The description states the tool is 'idempotent — reconnecting an open session is a no-op', but the annotations declare idempotentHint: false. This is a direct contradiction about a key behavioral trait. The description does add useful context about session-state mutation and auto-connect, but the contradiction makes the transparency unreliable.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds value: what it does, side-effect behavior, auto-connect context, and when to call it explicitly. No filler or repetition of schema fields.

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-optional-parameter connection tool with no output schema, the description covers purpose, side effects, and usage context well. It loses one point because the idempotency claim conflicts with the annotation, which could mislead an agent reasoning about call safety and retry behavior.

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 parameter 'device', including the omit-to-use-focused-tab guidance. The description does not add further parameter-level detail, but the schema already handles it, 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 clearly states the action ('Open a RALE / App Connector session'), the target ('the device's running Dev App'), and distinguishes this tool from siblings by noting it is rarely needed explicitly because other tools auto-connect. This gives an agent a precise sense of the operation and its place among related tools.

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

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

The description explicitly says when to use the tool ('to pre-warm the session or surface connection errors early') and, more importantly, when not to use it ('You rarely need to call this explicitly') while naming the alternatives that auto-connect. This is strong 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?

The description explicitly says the tool is 'not read-only' and mutates session state, which aligns with readOnlyHint=false. However, it also claims the tool is idempotent ('closing an already-closed session is a no-op'), while the annotation idempotentHint=false. This is an annotation contradiction, making the behavioral metadata unreliable.

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 action, followed by a behavioral note and usage guidance. The three sentences each carry distinct information with no filler. The 'not read-only' clarification and idempotency note are useful despite the conflict with annotations.

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

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

For a single-optional-parameter tool with no output schema, the description covers purpose, usage, and mutation behavior well. However, the idempotency contradiction with the annotations leaves the agent with conflicting signals, which is a meaningful completeness gap for a state-mutating 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 only parameter, 'device', is already fully documented in the input schema with details about IP, serial, and fallback to the focused Dev Studio tab. The tool description adds nothing meaningful beyond 'targeted device,' 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 uses a specific verb and resource: 'Close the RALE / App Connector session on the targeted device.' This clearly identifies the tool's action and distinguishes it from siblings like app_connector_connect or telnet_disconnect. An agent can tell what this tool does without needing to infer from the name alone.

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 concrete use cases: 'free the session or force a clean reconnect.' It also provides an explicit when-not-to-use signal: 'normal RALE tools do not require you to disconnect between calls.' It does not name a specific alternative tool, but the usage context is clear enough.

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

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

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 provide idempotentHint, readOnlyHint=false, and openWorldHint. The description adds detail beyond those hints: the side effect of opening a tab, the state change of focusing/making the device active, and the specific no-op condition ('a no-op if that device is already connected and focused'). It confirms rather than contradicts 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 dense sentences, zero filler. The core behavior and purpose are front-loaded, the parameter requirement follows, and the idempotency/exclusion guidance is last. Every sentence earns its place and no information is repeated.

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 no output schema, the description is remarkably complete: it covers the behavior, the side effects, idempotency semantics, prerequisites (device must come from list_devices/scan_devices), exclusions (ECP ops), and an alternative (test_connection). No critical decision-making 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?

Schema description coverage is 100%, so the schema already fully documents the 'device' parameter (required non-empty string, IP or serial formats, example values, source). The description reinforces that it is required and restates the source (list_devices / scan_devices), but adds little semantic value beyond what the schema already 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 names a specific verb ('Open (or focus...)'), a specific resource ('Dev Studio device tab'), and the concrete outcome ('making it the active target for renderer-routed tools'). It identifies which sibling tools depend on it (rale_command, telnet_*, app_function, get_telnet_log), so an agent can distinguish it from the other 50+ tools without opening any 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 states when to use the tool (before renderer-routed tools), when it is NOT needed ('Not needed for main-direct ECP ops'), and names the alternative for a related goal ('use test_connection to verify reachability without opening a tab'). This is textbook when/when-not/alternatives 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 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description reveals important behavioral details: it is a safe no-op when a healthy session exists, it tears down and reconnects only when stale/errored, and it returns an actionable error when the port is closed. The single-client caveat also explains why the tool avoids breaking working sessions. 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?

The description is longer than average, but every sentence carries operational value: prerequisite status, port conditions, no-op behavior, reconnect semantics, and return shape. It is front-loaded with the core purpose and required-first warning. Slightly dense, but not padded.

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

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

For a tool with no output schema and one optional parameter, the description is remarkably complete. It explains preconditions, error conditions, idempotent behavior, side effects, and the success return shape ({ ip, state }). An agent has enough context to invoke it correctly and to decide whether to call it at all.

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 already fully documented in the schema. The description does not add new parameter-specific semantics beyond the schema, which fits the baseline of 3.

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

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

The description uses a specific verb and resource: 'Open a BrightScript debug session to the Roku on control port 8081.' It also clearly distinguishes itself as the required prerequisite for all other debugger_* tools, so an agent can immediately tell it apart from siblings like debugger_status 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?

Provides explicit when-to-use guidance: call debugger_status first, and skip attach entirely if already attached/running/stopped. It also explains prerequisites (channel must be launched with debugging) and states that a plain sideload does not open the port, so the agent knows when the tool will fail and how to react.

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 this as non-read-only and non-idempotent, so the description adds value by explaining what the mutation does (resume until next halt) and how the next halt is observed. It does not expand on error behavior or whether the call blocks until stopped, but the described flow is sufficient.

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

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

Three short sentences carry the action, the follow-up, and the precondition with no filler. Important constraints are front-loaded, making the tool easy to scan and act on.

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-optional-parameter operation with no output schema, the description covers the trigger, termination conditions, and next step. It could add the return/response behavior, but the explicit 'use debugger_wait_for_stop' guidance makes the expected interaction complete enough.

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 only parameter, device, is fully documented in the schema (optional IP/serial or focused tab). The description adds no parameter-level detail, which is acceptable given 100% schema coverage; 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?

States a specific verb (Resume) and resource (execution from a halted state), and characterizes the behavior precisely: run until the next breakpoint, STOP, or error. This clearly distinguishes it from siblings like debugger_step (single step) and debugger_pause (halt execution).

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 gives the precondition 'Only meaningful while stopped' and prescribes the follow-up call debugger_wait_for_stop, giving the agent a usage sequence. It does not enumerate when not to use it or name alternatives, but for this tool the context is clear enough.

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

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

Annotations already indicate the tool is mutating and idempotent. The description adds useful behavioral context: it is a no-op if not attached and the running channel keeps executing. It also mentions the socket release, making side effects clear.

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

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

The description is very short, direct, and free of filler. It packs the core action, a technical detail, idempotency, and the effect on the running channel into two clear sentences.

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

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

There is no output schema, but the description provides enough behavioral context for a developer to understand the tool's effect, including the no-op case and that execution continues. Combined with the sibling tool list, it is sufficiently complete for a detach operation.

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 only parameter, device, is fully described in the schema with optionality, matching requirements, and fallback behavior. The tool description adds no extra parameter detail, and with 100% schema coverage, 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 clearly states the action: closing the debug session for a device, and adds a concrete detail about releasing the 808 control socket. This distinguishes it from sibling tools like debugger_attach, debugger_pause, and debugger_status.

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 when to use this tool—when you want to end a debug session—and the idempotent/no-op behavior makes it safe to call even if not attached. However, it does not explicitly name alternatives such as debugger_attach or debugger_disconnect, so the guidance is mostly implicit.

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 annotations by explicitly warning about side effects ('Can have side effects (it executes code), so it is not read-only') and explaining output behavior (streams to console, reports compile/runtime errors). It also adds the HALTED requirement, which is critical for correct invocation. 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?

The description is compact, front-loaded with the core purpose and an example, and each sentence adds necessary context (prerequisite, side effects, alternative tool, scope selection). No filler or redundancy.

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

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

For a tool with no output schema, the description fully covers what the agent needs: what it executes, the required halted state, side effects, output routing, error reporting, scope selection, and a pointer to a simpler alternative. Nothing essential is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by giving example expression syntax ('print m.top.count') and clarifying that stackFrameIndex/threadIndex select scope, which aids interpretation beyond the schema's basic 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 'Run', the resource 'BrightScript expression/statement in the halted frame', and specifies the REPL context with concrete examples. It also explicitly contrasts with debugger_get_variables for plain reads, distinguishing it from a 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 states when to use this tool (halted frame, REPL), the prerequisite that the target must be HALTED, and provides an explicit alternative (debugger_get_variables) for plain variable reads. This gives clear 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering safety. The description adds valuable behavior: the requirement for the target to be halted, the ordering of frames (top first), and that the frame index is used as input elsewhere. 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 concise sentences: purpose, requirement, and downstream usage. No fluff. The primary action is front-loaded, and each sentence adds distinct value. Efficient and well-structured.

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

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

For a read-only introspection tool with only two optional parameters and no output schema, the description covers all essential aspects: output content and ordering, prerequisite (halted), and how the result is used. Nothing critical is missing 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 description coverage is 100%, so both parameters (device, threadIndex) are already documented. The description mentions threadIndex's default (stopped/primary thread) but that is already in the schema. It doesn't add new parameter meaning beyond what the schema provides, so 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 action ('Return the call-stack frames') with specific details (function, file, line, top frame first) and the context (halted thread). This distinguishes it from sibling tools like debugger_get_variables and debugger_evaluate, which serve different purposes. No ambiguity about what the tool does.

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

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

It explicitly requires the target to be HALTED, a critical precondition, and explains how the output feeds into other tools (stackFrameIndex for debugger_get_variables/debugger_evaluate). It doesn't explicitly state when not to use it, but the halted requirement and output usage give clear context. Alternatives are implied through sibling tool names.

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, openWorld, and idempotent hints, so safety is covered. The description adds substantial behavioral detail beyond annotations: response entry structure (name, type, value, childCount), container response format, path segment semantics (quoted key case-sensitive AA lookup, bare number array index), and defaults for stackFrameIndex and threadIndex. 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?

The description is dense but every clause earns its place: purpose, response format, path mechanics, and defaults. It is front-loaded with the core action, and the optional parameters are listed at the end. 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?

For a debugger inspection tool with no output schema, the description fully covers what an agent needs: the halted prerequisite, response shape, how to traverse containers, and all parameter defaults. Nothing critical is missing 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% with descriptions for all four parameters, so baseline is 3. The description enriches this by explaining variablePath semantics in detail (e.g., ['m','top'] vs quoted 'key' forcing case-sensitive lookup) and stating defaults for stackFrameIndex (0 = top) and threadIndex (stopped/primary thread), which are not in 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 precise verb and object: 'Return variables in scope at a stack frame while HALTED.' It clearly distinguishes this from siblings like debugger_get_callstack (stack frames) and debugger_evaluate (expressions) by focusing on variable inspection, and it specifies the halted condition.

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 clear context: use when halted, and explains how to drill into containers via variablePath. It does not explicitly contrast with sibling tools, but the purpose is unambiguous and the description gives a concrete scenario ('while HALTED') and optional drill-down 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful context beyond those hints by defining the return fields, especially the distinction between 'verified' (registered on the device) and 'queued' (waiting for the next halt). This goes beyond the schema and helps predict 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-structured sentence that leads with the action and resource, then compactly enumerates the returned fields. Every clause adds useful information, and the field list is formatted cleanly with backticks. There is no filler or redundancy.

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

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

For a read-only list tool with one optional, fully documented parameter and no output schema, the description covers the essential return shape and field semantics. It does not mention pagination or related sibling tools, but those are not required for basic correct invocation. Minor gaps remain around edge cases like an invalid device identifier.

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% coverage for the single optional 'device' parameter, including how it resolves and when to omit it. The description only says 'for a device' and adds no extra parameter-level meaning, matching the baseline of 3 for fully covered schemas.

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 ('List the breakpoints') and clearly scopes it to 'the debugger is tracking for a device'. Listing the emitted fields further clarifies what the tool does and differentiates it from sibling tools like debugger_set_breakpoints or debugger_remove_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?

The description makes the read-only nature and device-scoped behavior clear, so an agent can infer this is for inspecting breakpoints rather than modifying them. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.

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 (readOnlyHint false, idempotentHint false), the description discloses 'best-effort' semantics and the precondition that it is only meaningful while running, providing additional behavioral insight.

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, uses two short sentences, and includes all 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?

The description covers the essential context: what it does, its best-effort nature, the precondition, and the follow-up step. It does not mention return values or errors, but given the simplicity and lack of output schema, 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 sole parameter (device) is fully described in the input schema with its optionality and usage. The tool description does not add further parameter-specific details, but given 100% schema coverage, the baseline 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 action ('Request a halt') and the target ('a running channel'), and specifies it is best-effort. It distinguishes from siblings like debugger_continue or debugger_step by focusing on pausing.

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

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

It provides explicit guidance on when it is meaningful (only while `running`) and directs the user to follow with debugger_wait_for_stop. It does not explicitly contrast with alternative debugger actions, but the context is clear enough for 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?

Even with idempotentHint/readOnlyHint annotations, the description adds real behavioral detail: removal is by file:line, queued breakpoints without device ids are also cleared, and the tool returns { removed }. This goes beyond what annotations or schema convey.

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 front-load the purpose, then define the input format, and finally explain an important edge case. No filler or redundant 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?

Covers input shape, source-of-truth for locations, queued-breakpoint behavior, and return shape. With the schema documenting the optional device parameter, nothing essential is missing for correct use.

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

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

The schema already documents all parameters, so the baseline is 3. The description adds value by clarifying that locations must match debugger_list_breakpoints output and that matching is by file:line, aiding correct invocation.

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 action 'Remove breakpoints by location' and identifies the exact input format. It also references debugger_list_breakpoints, distinguishing this tool from its set/list 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?

Clearly describes how to supply locations (array matching debugger_list_breakpoints) and why removal is keyed by file:line, giving practical usage context. It does not explicitly say 'use this instead of debugger_set_breakpoints,' but the purpose is unambiguous.

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

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

The description goes well beyond annotations by disclosing the pending behavior, the replacement of existing conditions on re-add, and the return of a breakpointId or error. This is valuable side-effect information that annotations (readOnlyHint=false, openWorldHint=true) do not cover.

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: a clear purpose sentence, a compact breakdown of the array structure, and then critical behavioral notes. Every sentence earns its place with no fluff 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?

For a mutation tool with no output schema, the description covers the parameters, the pending/queued behavior, return values (breakpointId or error), and re-add semantics. It does not detail error types or device matching specifics (which the schema covers), but is complete enough for correct use.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it explains path prefixing (bare paths get pkg:/), condition is a BrightScript expression requiring Roku OS 11.5+, and hitCount 'skips that many hits first'. These details enhance the schema's 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 action ('Add breakpoints') and specifies the exact resource and structure of the breakpoints array. It is unambiguous and distinct from sibling tools like debugger_remove_breakpoints or debugger_list_breakpoints by the verb and object.

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 crucial usage context—breakpoints are only registered while the device is halted, and adds are queued as pending otherwise. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is sufficient for correct 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the call is non-blocking, that 'stopped' means HALTED and safe to inspect, and that an attached session may already exist from the app's own debugger UI. This materially changes how an agent sequences its actions and is not present in 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 with no filler: the lead sentence gives the core result and state enum, the second gives a concrete pre-call decision, and the third gives polling guidance plus the alternative tool. Every clause earns its place and the most decision-relevant information 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 simple parameter-light, side-effect-free status tool, this description covers the state vocabulary, the safe-to-inspect condition, pre-call and polling use cases, and redirects to debugger_wait_for_stop for blocking behavior. The schema covers the device parameter, so 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 coverage is 100% and the single optional parameter is already well documented in the schema (Roku IP/serial, must match Dev Studio tab, omit for focused tab). The description adds no semantic detail 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?

States a precise action ('Return the session state'), a resource (device), and a key qualifier (WITHOUT blocking), then enumerates the possible returned states. It distinguishes itself from debugger_wait_for_stop by naming the blocking alternative, so an agent can tell them apart 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?

Explicitly tells the agent when to call this tool: before debugger_attach to check for an existing session, and as a poll to decide whether inspection tools will work. It also names when not to use it ('to block until the next halt use debugger_wait_for_stop instead'), which is textbook usage guidance.

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

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

Annotations already mark it as non-readonly and non-idempotent, and the description is consistent with that. It adds genuine context beyond the annotations: the HALTED precondition and the asynchronous protocol implied by 'Follow with debugger_wait_for_stop to get the new location', which tells the agent the step result is not returned directly. 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 zero filler and the core action front-loaded in the first clause. The kind enumeration earns its place by adding semantics rather than repeating the schema, and the HALTED plus wait_for_stop guidance is packed into two short sentences.

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

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

For a no-output-schema mutation tool, it covers the essential invocation context: the precondition, the parameter semantics, and where to obtain the new location (debugger_wait_for_stop). The remaining gaps are minor but real — the immediate return value of the step call itself and the failure behavior when the target is not halted are unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the bare enum: 'over' means next line skipping calls, 'in' enters the call, 'out' finishes the current function. It also confirms the default for kind. Device and threadIndex are already well documented in the schema, so no compensation needed there.

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 — 'Single-step the halted thread' — and enumerates the three step kinds (over/in/out) with their meanings. The verb 'single-step' and the HALTED precondition inherently distinguish it from debugger_continue and debugger_pause, but it never names an alternative explicitly, so sibling differentiation is implicit rather than explicit.

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 a clear when-to-use condition ('Requires the target to be HALTED') and workflow sequencing ('Follow with debugger_wait_for_stop to get the new location'). It does not, however, state when not to use it or name the alternative (debugger_continue) for free-running resume, which keeps it just short of fully explicit.

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 read-only/idempotent annotations, the description discloses blocking server-side polling, timeout behavior, successful halt results, timed-out results, and session-ended results.

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

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

The description is dense and well structured, with the primary blocking behavior front-loaded and return conditions plus usage guidance in compact sentences. The only minor repetition is the timeout default, but it does not hurt clarity.

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

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

Given there is no output schema and only two optional parameters, the description fully covers all return scenarios and specific usage context, leaving no important gap for an agent.

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

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

Schema coverage is 100% with both parameters already described in the input schema. The description only repeats the timeoutMs default/max and adds no new semantic detail beyond 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 clearly states the tool blocks until the target halts and returns a snapshot, using a specific verb and resource. It distinguishes itself from sibling debugger actions by focusing on waiting for a halt rather than initiating continue/step/pause.

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

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

It explicitly says to call it right after debugger_continue/debugger_step or after triggering the app, which tells the agent exactly when to use it to know when inspection is possible.

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?

States the side effect ('Changes device state (foregrounds the app)'), which is valuable context beyond the annotations. Does not contradict 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 containing essential information without fluff, though the first sentence is dense and could be split for readability.

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?

Provides enough context for an agent to call correctly, including the URL equivalent and explicit distinction from sibling. No output schema is present, but the action's return value is not critical for 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 covers all 5 parameters with detailed descriptions. The tool description repeats the contentId/mediaType/params pattern but adds little beyond the schema, so 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?

Clearly states it launches an app into specific content via ECP deep-link, and explicitly differentiates from launch_app by contrasting deep-link vs. home-screen launch.

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 provides when-to-use ('when you have a content id to open') and when-not-to-use ('to just open an app to its home screen use launch_app instead'), plus a concrete URL pattern.

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?

Description claims the operation is 'idempotent', but annotation idempotentHint is false, contradicting the annotation. Also notes destructive behavior, but the idempotency contradiction warrants a score of 1 per rubric.

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?

Concise and well-structured: front-loads the primary action, then provides relevant caveats about password and idempotency, and ends with guidance on the sibling tool. Each sentence serves a purpose.

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

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

Given the simple parameter set (no output schema, no enums, no nested objects), the description fully covers behavior, alternatives, and edge cases (deleting when nothing is sideloaded).

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 baseline is 3. The description only repeats the password-optional context already in the schema and adds no new meaning beyond the 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?

States the specific verb 'Remove' and resource 'currently sideloaded Dev App', clearly distinguishing from the sibling tool 'sideload' by explicitly directing install/replace to that 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?

Explicitly states when to use this tool (to delete) and when to use the alternative 'sideload' (to install/replace), including the note that no prior delete is needed because sideload overwrites. Also clarifies when password is optional.

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 readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds a side-effecting warning and a safer-alternative advisory, but it does not detail what consequences an arbitrary POST may have or what resources might be affected. Given the annotations carry the core safety profile, this is adequate but not rich.

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 short sentences with no wasted words. The core action is front-loaded, followed by a safety warning and a routing alternative. 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 raw POST tool, the schema fully documents parameters and the annotations cover the safety profile. The description provides purpose and alternative routing. The only minor gap is the lack of any mention of return values or error behavior, but this is not critical for selecting and invoking the tool correctly.

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

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

Schema description coverage is 100%, so both device and endpoint parameters are already documented in the schema. The description repeats 'arbitrary endpoint' and provides an example but does not add meaning 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 states a specific action ('POST') applied to an arbitrary ECP endpoint, with a concrete example. It explicitly distinguishes itself from ecp_query and list_post_presets, so an agent can tell what this tool is for 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?

The description gives explicit routing guidance: use list_post_presets for safe defaults, and use ecp_query for read-only lookups. This clearly tells an agent when to prefer alternatives and, by extension, when this raw POST tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's statement 'Read-only — does not change device state' reinforces without contradicting. It adds the positioning as 'go-to inspection tool' which is contextual, but no new behavioral traits beyond what annotations provide. The description is consistent and adds a small amount of extra context.

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 purpose and examples, followed by read-only clarification and routing to the alternative. Every sentence earns its place with no redundancy.

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

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

Given only two parameters, no enums, and no output schema, the description covers the essential information: what the tool returns, how to choose endpoints, and when to use alternatives. The annotations already handle safety, so nothing critical is missing 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% with parameter descriptions, but the description adds meaningful guidance: it explains endpoint selection via list_query_presets or /query/* paths, and specifically suggests '/query/apps' for enumerating app IDs. This goes beyond the schema's examples and helps the agent choose the correct parameter values.

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 runs read-only ECP GET queries for device information, lists example payloads (device info, installed apps, etc.), and distinguishes it from the sibling ecp_post by noting it is for inspection. It names the alternative and the exact condition to choose it, so an agent can easily tell this tool apart.

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 ecp_post as the alternative for state-changing operations and instructs how to enumerate app IDs via '/query/apps'. It also mentions using list_query_presets or any /query/* path, giving clear context on when to invoke this tool versus others. No ambiguity remains.

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 and idempotentHint, and the description repeats 'Read-only' (consistent). It adds workflow context (order relative to list_action_types and validate_script) that isn't in annotations, which is useful. No 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?

Three sentences, each earning its place: purpose, workflow trigger, and alternative. No fluff, front-loaded with the core action.

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 read-only tool with no output schema, the description covers when to call, what it returns, and the alternative. 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?

Schema coverage is 100% with a clear enum and description. The description adds cross-referencing to list_action_types for the valid values, reinforcing the parameter's meaning beyond 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 specific verb and resource: 'Return the authoring schema ... for ONE Action Script step type'. It clearly differentiates from siblings by scoping to a single step type and explicitly names the related tools (list_action_types, validate_script, get_capability_bundle).

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 guidance: call after list_action_types when authoring/fixing a specific step, and prefer get_capability_bundle for the whole contract. This clearly routes the agent to the right tool at the right time.

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 this read-only and idempotent, and the description reinforces that with 'Read-only.' Beyond annotations, it discloses the underlying ECP endpoint, the exact image dimensions, the base64/data URL return format, and the special 'dev' app id — genuinely useful behavior context for a tool with no output schema.

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 tightly packed sentences with no filler. The core operation and format come first, followed by id discovery, then the explicit sibling distinction. 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 two-parameter read-only tool, the description covers the return format, endpoint, id discovery, default-device behavior (implied by the schema's optional device param), and the key alternative (screenshot). Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, and both parameters already include examples and guidance ('837' for YouTube, device IP/serial examples). The description adds the 'dev' shortcut and ECP route hint, but the schema already carries the semantic load, so the added value over the schema is modest.

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 precise resource ('336x210 app icon for one installed channel'), and the returned format ('base64 / data URL'). It also distinguishes itself from screenshot by naming what it is for (previewing branding) versus capturing 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?

Explicitly tells the agent when to use this tool (previewing a channel's branding) and when not to (use screenshot for the current screen). It also tells the agent how to discover valid app ids via ecp_query or launch_app's notes, 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 indicate read-only and idempotent behavior. The description adds value by recommending caching and noting an alternative resource URL, which are not covered by 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 extremely concise with two sentences. The first defines content, the second provides usage guidance. No unnecessary 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?

For a tool with no parameters and no output schema, the description fully covers what the tool returns (listing all types), when to use it (before scripting), and additional context (caching, alternative resource).

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 no parameters, so description does not need to add param details. The baseline score of 4 applies as there is nothing to improve.

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 a single payload of all static capabilities, listing specific types (actions, vocabularies, etc.). This distinguishes it from sibling tools like get_action_schema which return individual items.

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 advises loading once before authoring scripts and caching, providing clear usage context. It doesn't explicitly exclude use cases, but the guidance is sufficient for a data-fetching 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 provide readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavior: the possible empty/null result when no tab is focused, and representative return fields. It does not contradict annotations and supplies context beyond the structured fields.

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: it leads with the return value, clarifies the empty case, then gives the call context and sibling alternatives. Every sentence serves a purpose and there is no redundancy.

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

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

For a zero-parameter, read-only getter with no output schema, the description is fully sufficient: it explains what is returned, the null/empty case, when to invoke it, and how it differs from related tools. 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?

The tool takes zero parameters, and the schema confirms this with 100% coverage. With no params, the baseline is 4; the description does not invent parameters and correctly focuses on output and usage semantics.

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

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

The description names a precise verb ('Return'), a specific resource (the single device tab currently focused in Dev Studio), and an explicit empty/null outcome. It also differentiates itself from list_devices and connect_device, so an agent can identify the tool without inspecting 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?

It explicitly states when to call the tool ('resolve the implicit target before a device op when the user says "this device" / "the current one" and gave no IP') and names the alternatives for full inventory (list_devices) and changing focus (connect_device). This is clear, actionable 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?

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 mark the tool as not read-only and not idempotent, and the description reinforces this while adding a useful behavioral detail not captured by the annotations: repeated calls append to the focused field. It also discloses the mutation target and the focus precondition. Minor credit is lost because some wording simply restates the annotation flags rather than adding entirely new behavioral context.

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 filler; every sentence earns its place: purpose/endpoint, precondition, mutation semantics, and guidance versus keypress. The core purpose is 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 simple two-parameter tool with no output schema, the description is complete: it states what the tool does, when it can be used, what side effects it has, and which alternative to use. The schema and annotations cover the remaining details, so 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%: both 'text' and 'device' are already explained in the input schema. The description adds no new parameter-level detail, so the baseline score of 3 is appropriate since the schema carries the full parameter documentation burden.

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 ('Type') and resource ('a literal text string into whatever input field is currently focused'), explicitly names the ECP /input endpoint, and clearly distinguishes itself from keypress by noting it is the better alternative to sending characters as individual keys. An agent can confidently tell this tool apart from its 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?

Gives an explicit precondition ('Requires a text field to already be focused') and names the sibling tool to use first ('use keypress to navigate into one first'). It also tells the agent when to prefer this tool over keypress with a direct statement: 'Use this instead of sending characters as individual keypress keys.'

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?

While annotations already mark readOnlyHint=false and idempotentHint=false, the description adds meaningful context by explaining that each call advances the UI and repeated calls are not a no-op. This goes beyond the structured annotations and helps the agent understand real consequences.

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

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

The description is compact and front-loaded with the core purpose. Every sentence contributes: what it does, the mutation caveat, and when to use an alternative. No redundant or filler content.

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 no output schema, the description adequately covers purpose, side effects, and alternatives. It slightly misses potential caveats like device targeting specifics, but the schema covers the device parameter well enough.

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 example key values and refers to list_keypress_options for the full set, but the enum already enumerates valid values. No additional parameter semantics are provided beyond 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 clearly states the tool sends one ECP remote key to a Roku device, mirroring a physical remote press. It uses specific verbs and resources and distinguishes itself from input_text by explicitly scoping to navigation/transport keys versus text entry.

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?

Explicit guidance is provided: use keypress for navigation/transport keys, and use input_text for typing characters. This directly names the alternative and the condition that selects it, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is known. The description adds valuable context: it changes device state (foregrounds the app) and passes launch params through as ECP query params, which is not present in annotations. This goes 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, front-loaded with the core action, then immediately addresses the alternative and param behavior. Zero filler, every clause 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?

The description covers purpose, state change, alternatives, and param handling. It omits error conditions and edge cases, but for a launch tool with a single required parameter, this is sufficient. No output schema is present, but the return value is likely trivial and not essential 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 all parameters are documented, but the description adds meaning: appId can be discovered via ecp_query, 'dev' is a specific sideloaded app, and the params object is passed through as ECP query params. This enriches understanding beyond the schema definitions.

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 (launch) and resource (channel/app by app id) with a clear goal (home screen). Explicitly differentiates from the deep_link sibling by naming it and the condition for using it. Purpose is unmistakable.

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

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

Provides explicit guidance on when to use this tool versus deep_link, and how to discover app ids via ecp_query. The description fully covers selection criteria and prerequisites, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces read-only status without contradicting them. It adds return-content detail (label, description, required/optional fields) but discloses nothing beyond that; the low-risk profile is already captured by 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 a clear front-loaded purpose, followed by workflow guidance and alternatives. Each sentence adds value; there is 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 zero-parameter, read-only listing tool, the description covers the return contents, its position in the authoring workflow, and alternative entry points. Nothing an agent needs to decide whether to call it 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 has zero parameters and 100% schema description coverage, so there is no parameter documentation burden. The description does not need to add parameter semantics.

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

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

Identifies the exact operation: return every Action Script step type with label, description, and required/optional fields. It distinguishes itself from get_action_schema, which provides exact fields for one type, and clearly situates itself as the starting point in the authoring workflow.

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

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

Explicitly directs when to use the tool: 'Start here when authoring a script', and names the subsequent calls to make (get_action_schema, validate_script, send_script_to_builder). It also names get_capability_bundle and a resource as alternatives for the full contract.

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, and idempotentHint, covering safety and idempotency. The description adds valuable behavioral context: the return structure (each entry with name, params, optional description), the instruction to surface descriptions verbatim, and the 'live' nature of the data. This goes beyond annotations by explaining output handling and source.

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) and well-structured: it starts with the purpose, then details the return format, then gives usage guidance, and finally mentions the optional parameter. Every sentence provides necessary information with no fluff.

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

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

For a simple listing tool with no output schema, the description fully covers what an agent needs: what the tool does, what it returns (structure and fields), when to call it, and how to handle the optional description field. It lacks nothing critical for correct invocation and interpretation.

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 only parameter, device, is fully described in the input schema with details about IP/serial and Dev Studio matching. The tool description merely repeats 'Optional device (IP or serial)' without adding new meaning. Since schema coverage is 100%, the baseline of 3 applies; the description adds no additional 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 clearly states the tool's function: listing live function metadata (name, params, optional description) from RALE's getExternalControlFunctions. It specifies the exact resource (app connector functions) and the verb (list), and distinguishes itself from siblings like app_function (which executes) and app_connector_connect/disconnect (connection management) by focusing on metadata retrieval.

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 call this tool before authoring appFunction steps, providing a clear usage context. It does not mention alternatives or exclusions, but the primary use case is well defined. The optional device parameter is also noted, but no when-not-to-use guidance is given.

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, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it enumerates the exact returned fields, clarifies the tool performs no network probing, and defines what 'known' means (connected, discovered, remembered, remote). 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?

The description is longer than average but every sentence earns its place: core behavior, field list, usage instruction, and sibling differentiation. The most important information (what the tool returns, that it doesn't scan) is front-loaded, and the field enumeration is valuable given there is no output schema.

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

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

Since there is no output schema, the description carries the burden of explaining return values, which it does thoroughly by listing all eight fields. It also covers usage context, safety (read-only), and relationship to siblings. For a zero-parameter, schema-less tool, 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?

The tool has zero parameters, so the baseline of 4 applies. The description contains no redundant parameter information, which is appropriate since none exist. It correctly focuses on the output and usage context instead.

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 ('Return') with a concrete resource ('every device Dev Studio already knows about') and clearly scopes the behavior ('without running a network scan'). It proactively distinguishes itself from get_selected_device, scan_devices, and connect_device, leaving no ambiguity about what this tool is 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?

Explicitly instructs the agent to use this tool as the first step to resolve a `device` argument for other tools. It also names three sibling tools and states exactly when each is the right choice, providing both positive usage guidance and clear exclusions.

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 provide readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds a prerequisite ('Requires Network Inspector enabled'), explains that aggregation happens 'in one call', and outlines what the response contains, going 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?

Two sentences, no filler. The first sentence front-loads the tool's purpose and output categories, and the second packs usage context, filter relationship, and a prerequisite. Every clause 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?

Despite lacking an output schema, the description lists the aggregate categories (event type, status class, top hosts, content types, transaction counts, error count, largest responses), so an agent knows what to expect. It covers usage context, filter semantics, and the enablement prerequisite, making it complete for a read-only aggregation tool.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds value by stating that this tool 'Accepts the same optional filters as network_inspector_list_events', letting the agent reuse its knowledge of a sibling tool's filter semantics—a meaningful enhancement beyond 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?

States a specific verb ('Aggregate') and resource ('captured buffer') and enumerates the exact rollups produced. It explicitly contrasts with 'drilling into individual events', distinguishing it from siblings like network_inspector_list_events and network_inspector_get_event_detail.

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

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

Gives clear context: 'Use this to orient on a session before drilling into individual events,' which signals when to choose it over event-level tools. It also references network_inspector_list_events for filter compatibility, though it does not explicitly state when not to use 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?

Beyond the annotations (readOnly, idempotent), the description discloses important runtime behavior: what parts are searched, the return shape (total, scopes, inline summary), and the safe degradation of dangerous/over-long regex patterns to literal search. It also communicates that omitting device searches all Rokus with captured traffic, which is non-obvious behavior an agent needs to know.

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 front-loaded with the core distinguishing behavior first, then use cases, result summary, and parameter guidance. Every clause delivers actionable information, and the backtick-delimited parameter names improve scannability. The length is justified by the tool's six parameters and absence of an output schema.

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

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

With no output schema, the description provides the essential return details inline (total, scopes, event summary) and covers all parameters, defaults, and the prerequisite. It also gives cross-references to sibling tools, leaving no significant gap for an agent to select and invoke the tool correctly.

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

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

Even though the schema already covers 100% of parameters, the description adds meaningful semantics for each one: query is required, scopes narrows search parts or defaults to all, caseSensitive defaults to false, regex has fallback behavior, device is optional and scoping is described, and limit has default/max values. This goes well beyond the schema's bare 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 opens with a specific action and resource: 'Search the FULL content of captured transactions — request/response URL, headers, and bodies — for query'. It immediately contrasts itself with network_inspector_list_events' host filter and pinpoints the exact use case ('which request(s) contain X'), making its purpose unmistakable.

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

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

It explicitly tells the agent when to use this tool versus siblings: it names network_inspector_list_events as the wrong tool for full-content search and get_event_detail as the slower, page-by-page alternative. It also states the prerequisite ('Requires Network Inspector enabled') and points to network_inspector_status, giving clear contextual 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, so the safe, side-effect-free nature is established. The description adds behavioral context by explaining that the returned snippet is needed to trust the proxy and enable HTTPS decryption, which is useful for the agent to advise the user. 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?

Two sentences with no filler: the first lists exactly what is returned, the second gives the precise condition for using it. The information is front-loaded and every word contributes.

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

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

Even though there is no output schema, the description specifies the three return components (fingerprint, proxy host:port, BrightScript snippet) and their purpose. For a zero-parameter informational tool, this is enough for an agent to know what to expect and how to use 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, and the schema confirms an empty object with 100% coverage. The description, therefore, doesn't need to document any parameter behavior, and the baseline for 0-parameter tools 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 uses the specific verb 'Return' and names the exact resource objects: 'CA fingerprint, proxy host:port, and the BrightScript snippet.' It also states the purpose—making HTTPS request/response bodies visible to the Network Inspector. By referencing network_inspector_list_events, it helps distinguish this tool from that 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 an explicit conditional trigger: 'Use when network_inspector_list_events shows TLS handshakes but no decrypted HTTP bodies.' This is a clear when-to-use signal. It doesn't name an alternative tool, but it doesn't need to since no other tool appears to fill this role; the condition 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 declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral details beyond annotations: body truncation cap (maxBodyChars default 4096), warnings on truncation, includeFullBody override, and no body events potentially returning 404. 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, no unnecessary words. Front-loaded with action and key details. Very 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?

Given the tool has 3 parameters and no output schema, the description covers all critical aspects: what it retrieves, truncation behavior, edge cases, prerequisites. It is complete for an AI agent.

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

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

Schema coverage is 100% and description adds significant context: id is from list_events, maxBodyChars default 4096, includeFullBody overrides truncation behavior. Provides value beyond the schema itself.

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

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

The description clearly states the action 'Fetch the full headers and body for one captured event by id' and specifies the resource (network event). It distinguishes itself from siblings by referencing 'network_inspector_list_events' as the source of the id.

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 mentions the prerequisite 'Requires Network Inspector enabled' and notes edge cases (DNS/TLS/TCP events may return 404). However, it does not explicitly state when to use this tool versus alternatives (e.g., list_events for listing) but implies the use case.

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, and idempotentHint, and the description adds substantial behavior beyond those: summary-first design to protect context, AND-OR filter composition, most-recent ordering, errorsOnly as a shortcut, and the requirement on Network Inspector being enabled. No contradictions 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?

The description is dense but efficiently organized: core action and summary-vs-detail distinction first, then filter semantics, then ordering and prerequisites. Every clause earns its place, and the use of parentheticals keeps the long filter list compact without losing precision.

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 10 optional filters and no output schema, the description covers all filter behaviors, result shape (lightweight summaries with event IDs), ordering (most-recent), prerequisite status, and the path to more detail. Nothing an agent needs to invoke 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?

Even though schema coverage is 100%, the description adds critical semantic value: filters are AND-combined, arrays OR within a field, with a concrete example (status: [404, 500]). It also clarifies defaults, case-insensitive substring matching, the meaning of errorsOnly, and the omit-device shortcut — all beyond the parameter descriptions in 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 specific verb and resource ('List captured network events') and immediately differentiates itself from the detail-retrieval sibling by noting it returns 'lightweight summaries (no full headers/body — drill down with network_inspector_get_event_detail)'. This makes its role in the Network Inspector family unmistakable.

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

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

It explicitly provides the when-to-use alternative: use this for summaries, drill down with network_inspector_get_event_detail for full details. It also states the prerequisite ('Requires Network Inspector enabled (see network_inspector_status)') and clarifies the default scope (all Rokus when device is omitted).

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 safe read-only behavior. Description adds useful context on metrics reported and the condition that reads are useless until ready is true, which is valuable beyond 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?

Single sentence packs all essential info (purpose, fields, usage order). No superfluous text, but could be broken into two sentences for readability.

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 tool with no output schema, the description enumerates returned fields and remediation logic, providing sufficient completeness for an agent to understand what to expect.

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?

No parameters exist, so baseline is 4. Description explains the return fields (enabled, capturing, etc.) compensating for lack of output 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 the tool reports Network Inspector status including specific fields like enabled, capturing, client count, etc. It distinguishes from sibling network_inspector_* tools by being the status check.

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 instructs to call this first before other network_inspector_* tools and provides conditional guidance on using notice/remediation when ready is false.

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. Description adds context about return format and session usage, but behavioral traits are mostly covered by 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 concise sentences with clear structure; front-loads return format and essential usage instructions with no wasted words.

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

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

Despite no output schema, description fully explains return format and session flow. Complete for a probe tool given low 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?

No parameters exist; schema coverage is 100%. Description adds no param info, but baseline is 4 for zero-parameter tools.

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

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

Description clearly states the tool returns bridge status and distinguishes it from sibling tools by noting that once live=true, other tools can be used freely.

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 instructs to call once per session before first bridge-dependent tool and contrasts when to use direct ops vs re-probing.

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=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds value beyond those by disclosing the auto-connect side effect, the lookup scope (running Dev App via App Connector), and the path disambiguation behavior for non-globally-unique ids. It opens with 'Read-only,' which is consistent with readOnlyHint=true — 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?

The single ~115-word paragraph front-loads purpose and alternative routing before the parameter explanations, so the most decision-relevant information comes first. The parameter sentence slightly overlaps with the 100%-covered schema, but it adds disambiguation and default-behavior nuance that the schema lacks, so the length is justified rather than padded.

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, 3-parameter tool with no output schema, the description covers operation, prerequisites, parameter defaults, disambiguation logic, and the boundary with rale_command. Return shape is hinted ('its fields / children'), and error behavior is omitted, which is acceptable at this complexity level given the strong annotations and fully described schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that path is for disambiguation 'when the id is not globally unique' and that omit/[] means 'global lookup' — a step beyond the schema's 'use [] or omit for root.' It also specifies the device default ('omit for the focused tab'), which the schema's 'for a specific Dev Studio device tab' does not convey.

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: 'fetch one SceneGraph node (its fields / children) by its id from the running Dev App via the App Connector.' It also explicitly frames itself as a 'convenience wrapper over rale_command getNodeById,' which distinguishes it from the generic sibling rale_command. An agent can tell exactly what this tool does 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?

Provides explicit routing guidance: 'Use this — not the general rale_command — for the common inspect-one-node case; drop to rale_command only for other RALE built-ins (registry, focus, other queries).' The prerequisite is also stated ('Requires a connected App Connector session (auto-connects if needed)'), leaving no ambiguity about when to select this tool over its alternative.

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

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

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?

The annotations declare destructiveHint: true and readOnlyHint: false, while the description depicts a benign capture-and-return operation with no side effects. A screenshot capture is fundamentally non-destructive, so the annotation directly contradicts the described behavior. This is flagged as an Annotation Contradiction; an agent relying on the safety annotations would be misled about this tool's side effects.

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 in the first sentence, followed by usage guidance and the password note. It is slightly dense, but every sentence earns its place — the returnImageBase64 guidance is essential for correct invocation, and the bold emphasis improves scannability.

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

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

Given there is no output schema, the description correctly carries the burden of explaining return behavior, covering both output modes. For a tool with 4 optional parameters and no required fields, it covers the essential invocation decisions. It omits error/failure behavior (e.g., unreachable device), but the core usage space is adequately covered.

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 meaning beyond the schema by explaining the two response shapes (inline image vs. '{ success, filename, bytes }'), the host rendering behavior, and the condition under which the password can be omitted. This gives the agent decision-relevant semantics the schema alone does not provide.

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 ('Capture a screenshot of the current device screen') plus the exact return mechanism ('MCP image content block (JPEG, base64)'). This clearly differentiates it from image-related siblings like get_app_icon, which captures an app icon rather than the live device screen. An agent knows exactly what this tool does and what it returns.

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 guidance: keep returnImageBase64 true (or omit it) 'for any human-facing capture,' and set it false ONLY for batch/metadata-only flows where no one will view the image. The password condition is also spelled out. It does not explicitly contrast with alternative tools or state when not to use screenshot at all, but the usage context provided is strong.

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

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

Adds context beyond annotations: does not auto-run, runs same validation as validate_script. No contradiction with annotations. Annotations already provide idempotent and open world 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?

Front-loaded with core purpose, then usage guidelines. Two sentences plus a longer instruction, minimal waste. Could be slightly tighter.

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 2 params, no output schema, and annotations, the description covers purpose, usage, and parameter shape. No output schema needed; completeness 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?

Schema coverage is 100%. Description mentions script and device parameters briefly but adds no new semantic information beyond what schema 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?

Description clearly states tool sends a validated Action Script to Dev Studio Builder for human review, distinguishes from siblings by mentioning direct ops 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?

Explicitly states when to use (multi-step/conditional/saved-or-reviewed flows) and when not (single deterministic action), listing alternative direct ops.

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 that it replaces any currently sideloaded Dev App and flags it as not safe for autonomous use, matching and contextualizing the destructiveHint=true annotation. It additionally reveals the temp-file write/cleanup lifecycle for contentBase64 and the actionable error for sandbox-looking filePath values — all behaviors 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 long but every sentence earns its place. It front-loads the purpose and destructive warning, then clearly structures the two input modes with their caveats. There is no filler; each sentence adds unique operational 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 destructive action with two input modes, optional password, no output schema, and five parameters, the description covers everything needed to invoke it safely: what it does, what it destroys, the exact conditions for each input mode, temp-file cleanup, password behavior, and error handling. 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 the baseline is 3, but the description adds meaningful decision-making context: mutual exclusivity of filePath and contentBase64, the same-machine requirement for filePath, the temp-file write/delete flow for contentBase64, and the 'omit if remembered' rule for password. These details go well beyond the schema's 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 first sentence uses a specific verb ('Upload and install') and resource ('.zip channel package on the device'), making the core action unambiguous. It also surfaces the destructive replacement behavior, which helps differentiate it from non-destructive tools. However, it does not explicitly name sibling tools like delete_sideload or launch_app, so it stops short of a 5.

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/not-to-use guidance: it warns against using filePath in a remote agent sandbox and directs agents to contentBase64 when no shared filesystem exists. It also states that the tool is 'not safe for autonomous use without user intent,' acting as a clear exclusion condition. This is exemplary usage guidance.

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

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

Directly contradicts the idempotentHint: false annotation: the description twice states 'Idempotent' and explains the already-attached behavior, while the annotation declares the tool is NOT idempotent. Even though the description otherwise does an excellent job disclosing the socket-displacement side effect and the read-only caveat, the contradiction rule mandates a score of 1.

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?

Front-loaded with purpose, but the description has visible redundancy: the idempotency claim appears twice ('Idempotent: returns { connected: true, already: true }' and 'idempotent — already-attached returns { already: true }'), and the socket-displacement warning also appears twice ('connecting here will displace...' and 'displaces other clients'). The repeated claims could be merged into one sentence without losing 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 tool with one optional parameter, no output schema, and modest complexity, the description covers all essential operational concerns: what it does, the return value shape even without an output schema, the prerequisite for get_telnet_log, and the non-obvious side effect of displacing other socket clients. Slightly diminished by the inaccurate idempotency claim, but as a standalone description it is nearly complete.

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% — the single optional 'device' parameter already documents 'IP or serial' and the focused-tab default. The description adds no parameter detail beyond the schema, so the baseline 3 applies. No compensation needed since the schema fully covers the one parameter.

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

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

States a specific verb ('Open'), a precise resource ('BrightScript debug console TCP 8085'), and draws an exact analogy to the user clicking the Connect button. The description clearly differentiates this from siblings like telnet_disconnect, get_telnet_log, and debugger_attach by naming the port and the UI action it emulates.

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 sequencing guidance: 'Lines do not accumulate until this is called' and 'After it returns successfully, poll the buffer with get_telnet_log({ afterCursor }).' This tells the agent when in a workflow this tool is required. It doesn't explicitly state exclude conditions (e.g., when to prefer debugger_attach or ECP), but for a tool with such a specific role, the context is clear and actionable.

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 and repeatedly claims idempotency ('Idempotent: returns...', 'idempotent — already-closed returns { already: true }'), while the annotation declares idempotentHint: false. This is a direct annotation contradiction that would mislead an agent relying on structured hints about retry and repeated-call behavior. Per the rubric, the score must be 1.

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

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

The purpose is front-loaded and the description is compact at ~70 words. However, the idempotency claim and return payload are stated twice ('Idempotent: returns { connected: false, already: true }...' and later 'idempotent — already-closed returns { already: true }'), which is redundant and costs efficiency. Adequate but not tight.

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 zero required parameters and no output schema, the description covers purpose, the connection resource, the side effect of closing the socket, the not-read-only nature, use cases, and the already-closed return shape. Missing only minor details like the success-path return value and error behavior; the annotation contradiction also undermines a complete agent model, preventing a 5.

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%; the single optional 'device' parameter is already fully documented ('Optional target device (IP or serial). Omit to use the focused tab'). The description's 'targeted device' phrasing adds no meaning beyond the schema, so the 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 ('Close'), resource ('BrightScript debug console (TCP 8085)'), and target ('targeted device'), with a concrete analog ('mirroring the Disconnect button'). The TCP 8085 detail and 'console' naming effectively distinguish it from sibling tools like telnet_connect, get_telnet_log, and the debugger_* family 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?

Gives explicit use cases: 'release the 8085 socket so another tool can attach, or to stop log accumulation.' This tells the agent when to invoke the tool. It does not explicitly name when-not-to-use conditions or alternatives (e.g., debugger_detach for the debugger session), so it falls short of a full 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only.' It adds behavioral context beyond annotations by noting that no Dev Studio tab must be open and that the tool returns basic device info.

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-load the action and scope, then state the key prerequisite exception and the sibling differentiators. Every sentence earns its place with no repetition 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?

For a one-optional-parameter read-only probe with no output schema, the description covers what it does, how to route around siblings, and what result type to expect ('basic device info'). Nothing needed for correct call selection is missing.

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

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

The schema fully documents the device parameter (IP, serial, or omit for focused device), so the description is not required to compensate. However, the tool description repeatedly says 'IP' and 'address,' which under-emphasizes the serial and focused-device options that the schema explicitly supports; the 'one known device' framing adds only modest clarifying value.

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 starts with a specific verb and resource: 'Probe one known device IP for ECP reachability and return basic device info.' It explicitly differentiates itself from probe_bridge and scan_devices, telling an agent exactly what makes this tool distinct.

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

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

It says when to use it ('confirm a specific IP is a reachable Roku before connect_device') and names the alternatives with their conditions: probe_bridge checks Dev Studio, scan_devices finds unknown devices. It also notes the Dev Studio tab is not required, which removes a common prerequisite concern.

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 tool as read-only and idempotent, and the description adds behavior beyond that: it documents the response shape (ok, errors[], stepCounts, humanSummary, referenceTools), states that ok=false surfaces as isError, and points to a contract resource. No annotation contradiction is present.

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

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

The description is compact and front-loaded with the core purpose, then provides response behavior, contract reference, and usage guidance in just two sentences. Every clause adds value, including the list of direct op alternatives.

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 validation tool with one fully documented parameter, the description covers purpose, usage boundaries, response fields, error convention, and a contract resource. It is complete enough for an agent to select and call the tool correctly, though it relies on the linked contract for deeper semantic detail.

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% and already describes the script parameter in detail, including the oneOf object/string form and the { steps: [] } requirement. The description's mention that script can be a JSON object or string adds no new semantics beyond the schema, so a 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 an explicit verb (validate), the resource (Action Script), and the workflow context ('before send_script_to_builder'), which immediately distinguishes it from the sibling builder tool and direct action operations. It is more specific than a generic 'validate script' label.

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 selection criteria: author scripts only for multi-step/conditional/polling/saved-or-reviewed flows, and for a single action use the named direct op. It also positions the tool as the validation step before sending a script, leaving no ambiguity about 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.