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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real context beyond them: the ADB prerequisite, that a missing setup produces an explicit error, that state is 'idle' when nothing plays, and that position_s is null for live TV. It stops short of describing latency, caching, or polling behavior, so it is strong but not exhaustive.

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 primary payload (what is reported) is front-loaded in the first sentence, with edge-case semantics and the prerequisite following in a tight second block. Every sentence carries information; nothing is redundant filler.

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

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

For a no-argument, read-only probe with an output schema, the description covers everything an agent needs that the structured fields do not: the setup prerequisite, the failure mode, and the two non-obvious value semantics (idle state, null position for live TV). Nothing material 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, so there is nothing for the description to disambiguate; per the baseline for a 0-parameter schema this lands at 4. The description correctly adds no parameter discussion and instead spends its words on return-value 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 gives a specific verb and resource ('Report what is playing') and enumerates the exact fields returned (app, title, subtitle, play state, position in seconds), so the agent knows precisely what it gets back. It does not, however, differentiate itself from the sibling get_status, which could plausibly also report playback state.

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

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

Usage is only implied: an agent can infer this is the tool for 'what's on right now,' and the idle/live-TV notes hint at when results are meaningful. There is no explicit statement of when to prefer this over get_status or how it relates to the other read-oriented 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 and openWorldHint=false, so the description correctly need not restate safety. It adds genuinely new behavioral context: the ADB (adb-setup) prerequisite and the meaning of a "stuck" remote including that advice on fixing it is returned. It stops short of describing pagination, timing, or failure modes when ADB is unavailable.

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 core purpose is front-loaded in the first sentence, and the state glossary is compact and readable. The state enumeration is somewhat long for a tool that also has an output schema, but each state's parenthetical adds diagnostic meaning rather than 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 zero-argument read tool with annotations and an output schema, the description covers what is returned (remote list plus per-remote state), the environment prerequisite (ADB), and how to interpret abnormal states. Only the absence of guidance on what to do next when a remote is disconnected keeps it from being fully 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema is empty and fully covered, and the description correctly spends no space on arguments.

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

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

The description states a specific verb ("List") and resource ("the Shield's Bluetooth remotes") plus the key payload ("whether each works"). No sibling tool (get_status, get_now_playing, list_apps) covers Bluetooth remotes, so the scope is unambiguous.

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

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

The diagnostic intent is implied by "whether each works" and the state glossary, but the description never says when to reach for this tool versus get_status or what to do with the results. No exclusions or prerequisites beyond ADB are given, so usage is inferred rather than stated.

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, so safety is covered. The description adds genuinely non-obvious behavior: stale=true signaling unreachable state, that power/app/volume are last-known values with as_of timestamping, and that error explains why. The dry_run note is somewhat tangential for a zero-parameter read tool but still adds 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?

Front-loads the key orientation phrase "Start here" and stays compact across two short paragraphs. The final dry_run sentence is loosely related to a no-param read tool and slightly dilutes focus.

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?

An output schema exists, so return values need not be restated, and the description still covers the ambiguity the schema cannot express: stale-value semantics, timestamp/error fields, and the distinction from get_now_playing. Nothing needed 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, so the baseline is 4. There are no parameter semantics to clarify, and nothing in the description misrepresents the empty 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+resource (get Shield status) and enumerates exactly what is returned: reachability, power state, foreground app, and volume. It also distinguishes itself from the sibling get_now_playing, so an agent can separate the two 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?

"Start here" gives explicit entry-point guidance, and the description names the boundary condition and alternative: it does not report what is playing, while get_now_playing does (if ADB is set up). That is an explicit when-to-use plus a when-to-use-instead.

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 idempotent=true and destructive=false, so safety is largely covered. The description adds genuinely new behavioral context: the call only succeeds once the app is actually in the foreground, and failures surface a Shield-specific error message — useful for an agent deciding how to interpret 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?

Two tight sentences; the identifier requirement and the success/error semantics are both front-loaded with no filler.

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

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

With an output schema present, return values need no explanation, and annotations cover idempotency and safety. The description covers the failure mode and success condition; only minor details (e.g. timeout behavior while waiting for foreground confirmation) are left implicit.

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 schema itself already says 'Friendly app name from list_apps, e.g. netflix'. The description's pointer to list_apps and its examples largely restate 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?

States a specific verb ('launch') and resource ('app') and immediately scopes the identifier source to friendly names from list_apps. An agent can distinguish it from the sibling list_apps without opening either schema.

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

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

It tells the agent to use friendly names 'see list_apps', which is the key prerequisite, and states the success condition (app confirmed in foreground). It doesn't state a when-not case, but for a single-purpose launch tool there is no competing sibling to exclude beyond list_apps.

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 openWorldHint=false, so the safe read-only profile is covered. The description adds that entries are friendly name -> link pairs, which is modestly beyond annotations, but since an output schema exists it largely restates return content rather than 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?

A single front-loaded sentence with zero waste; the purpose and the launch_app linkage appear immediately.

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 discovery tool with an output schema and covering annotations, nearly everything needed to call it is present. The only omission is an explicit statement of the intended sequencing relative to launch_app.

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, so per the rubric baseline is 4. There is nothing for the description to clarify about inputs.

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?

Specific verb (List) plus a precise resource (the app names launch_app accepts), and it even characterizes the return shape as a friendly-name-to-link mapping. This distinguishes it cleanly from siblings like launch_app, get_status, or get_remotes.

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?

By tying the returned names directly to launch_app's accepted input, it gives clear context for when to call it (discovery before launching). It stops short of an explicit 'call this before launch_app' instruction or any exclusion, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description goes well beyond them: it discloses the playback interruption, the ~1 minute duration, the blocking wait for the device to return, the post-reboot Bluetooth remote check with remediation advice, and the ADB (adb-setup) dependency. That is the behavioral context an agent needs before triggering an irreversible action.

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

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

Front-loaded with the action and the restriction before the mechanics, and every clause carries information (side effect, duration, post-check, prerequisite). The duration/remote-check sentence is slightly dense, but nothing is padding.

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?

An output schema exists, so return values need no explanation; the description still covers the two things an agent cannot infer from schema or annotations: the destructive playback side effect and the ADB prerequisite. Nothing needed 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, so the baseline is 4 and there is no syntax or format detail the description could add. It correctly avoids inventing parameters and instead spends its words on side effects.

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 ('Restart the Shield') and immediately scopes it against the sibling family: this is a reboot, not the power control offered by set_power or a key press. An agent can pick it apart from set_power/get_status 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?

Gives an explicit when-to-use gate ('Only do this when the user asks for a reboot') plus the consequence that selects caution ('it stops whatever is playing'). It does not name the alternative tool to use for plain power-off (set_power), so the routing is clear but not fully closed.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds only that repeat produces repeated presses, without disclosing what receives the key (focused app vs. system), latency/blocking behavior, or any prerequisite state such as the device being powered on.

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?

A single sentence that puts the verb and target first, then supplies the example. There is no filler and nothing redundant with the schema.

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

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

For a two-parameter input tool with an output schema (so return values need no explanation) and full annotation coverage, the description supplies the essential purpose plus one grounded example. It stops just short of stating when this tool should be preferred over higher-level siblings or whether the target must be focused/awake.

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 only 50% (the 'key' enum has no description) and 'repeat' is minimally documented ('How many times to press the key (1-10).'). The description compensates by tying repeat to an observable effect ('repeat=3 to move down three rows') and by framing the key values as Shield remote-control keys, which is genuine 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 ('Press') and resource ('a remote-control key on the Shield'), making it immediately distinguishable from siblings like launch_app, set_power, and get_status. An agent can tell this is the low-level input-injection tool 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?

Usage is implied by the concrete example (DPAD_DOWN with repeat=3 to move down three rows), which shows the intended navigation scenario, but the description names no alternatives and gives no explicit when-to-use/when-not-to-use guidance. It is adequate but leaves routing to inference.

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

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

Annotations already declare idempotency, non-destructiveness, and non-read-only, but the description adds command-level behavior: it uses WAKEUP/SLEEP rather than a POWER toggle and only succeeds after the Shield reports the new state. It also notes no command is sent if the Shield is already in that state, reinforcing the idempotent behavior beyond the annotation.

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

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

Three short sentences, front-loaded with purpose and mechanism. Every sentence earns its place by clarifying the value mapping, command choice, or success/no-op 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?

For a simple one-parameter state setter with output schema and safety annotations present, the description covers purpose, mapping, mechanism, success condition, and no-op behavior. It leaves failure/timeout behavior unstated, and sibling differentiation is only implicit via the command mechanism.

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. It does so fully by mapping each enum value to the real action ('on' = wake, 'off' = sleep).

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 specific verbs (wake/sleep) and the resource (the Shield), and maps them to the 'on'/'off' values. It also distinguishes the operation from a POWER toggle, though it does not explicitly contrast with the reboot_shield 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?

Usage is implied by the verb pair—the tool is for waking or sleeping—and the description adds the no-op condition when already in the desired state. However, it offers no explicit when-to-use/when-not guidance or routing to alternatives like reboot_shield or send_key.

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