roku_debug_variables

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates a non-mutating read operation ('Get variables') and explains drill-down and key-only listing behaviors. It does not mention side effects, prerequisites like a paused debugger, or error behavior when the frame or thread is invalid, leaving some transparency gaps.

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

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

The description is two sentences with no filler. The primary purpose is front-loaded, and the second sentence efficiently packs the two optional usage modes into compact instructional phrasing. 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?

The tool has four parameters and no annotations, and while an output schema exists, the description fails to explain frame_index and thread_index. It also does not state whether a debugger must be connected or paused. An agent could call this tool with the wrong frame/thread interpretation or without understanding the required runtime context.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It explains variable_path with a concrete example and get_child_keys with its purpose, but it completely omits frame_index and thread_index, which are central to selecting the stack frame. The explanation covers only half the parameters, leaving two important arguments undocumented.

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

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

The opening sentence 'Get variables visible in a stack frame' states a specific verb and resource, making the core purpose clear. It does not explicitly differentiate from siblings like roku_debug_stacktrace or roku_debug_threads, but the resource 'variables in a stack frame' is distinct enough for an agent to form a correct initial expectation.

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 usage instructions for variable_path ('drill into a container') and get_child_keys ('list a container's keys only'), which clarifies how to invoke the tool. However, it offers no guidance on when to choose this tool over sibling debug tools, nor does it state conditions such as requiring an active debug session. Usage context is implied rather than explicit.

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