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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing retry semantics ('Relative steps are not retried after uncertain failure'), which the agent cannot learn from 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 short sentences with no waste; the core relative-adjustment purpose is front-loaded and the retry caveat follows 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 two-parameter tool with full schema coverage, a complete annotation set, and an output schema, the description is nearly sufficient. The only omission is an explicit pointer to apple_tv_set_volume for absolute volume changes.

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 the 'steps' and 'direction' parameters are already documented in the schema, setting the baseline at 3. The description's phrase 'Relative steps' reinforces the semantics but adds no range, default, or format 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?

States a specific verb+resource ('Nudge volume up or down') and makes the relative nature of the operation clear, distinguishing it in spirit from the absolute-scaling sibling apple_tv_set_volume. However, it never names that sibling, so the differentiation relies on the agent inferring 'nudge' vs 'set'.

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 'Nudge' and 'Relative steps', which suggests this is for incremental changes rather than absolute levels, but there is no explicit when-to-use statement or mention of apple_tv_set_volume as the alternative for setting a specific level.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lowered. The description adds genuine value beyond them by enumerating the possible availability states (available, unknown, unavailable, unsupported) and clarifying the output scope as semantic rather than a raw UI dump.

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 the core purpose and each sentence earning its place: the enumeration clarifies return semantics and the final sentence blocks a plausible misreading. 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, the description needn't explain return structure, and zero parameters removes schema burden. The description is complete for a read-only capability probe, though a brief note on when to prefer it over apple_tv_status would fully close the gap.

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

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

The tool takes zero parameters, so there are no parameter semantics to document; per the rubric this sets a baseline of 4. The description correctly adds no misleading parameter information.

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

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

States a specific verb and resource ('Return current availability of semantic Apple TV operations') and explicitly differentiates from sibling-style tools by declaring 'This is not a screenshot or UI-hierarchy dump.' An agent can immediately tell this is a capability-discovery tool distinct from apple_tv_screenshot and apple_tv_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 negative framing ('not a screenshot or UI-hierarchy dump') implies when this tool is preferable, but there is no explicit when-to-use statement or guidance on querying it before attempting other operations. Usage is implied 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 and openWorldHint=false, covering the safety profile. The description adds little beyond that, only clarifying the scope to 'launchable' applications; it does not mention pagination, rate limits, or other behavioral traits. With annotations carrying the main burden, this is minimally viable.

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 is front-loaded and contains no wasted words. It efficiently conveys the essential purpose.

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

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

For a simple list tool with an optional filter, the description is complete enough: the output schema handles return values, the input schema documents the query parameter, and the annotations cover safety. No critical information for invoking the tool 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 single query parameter is fully documented in the schema. The description does not add any meaning beyond what the schema provides, which is appropriate given the baseline for high coverage.

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

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

The description states a specific verb (list) and resource (launchable applications installed on the Apple TV), clearly distinguishing it from siblings like apple_tv_open_app. However, it does not explicitly name or contrast with any alternative tool, so it falls short of the top score.

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 no guidance on when to use this tool versus alternatives such as apple_tv_status or apple_tv_capabilities. While the purpose implies a straightforward listing operation, no explicit context, prerequisites, or exclusions are provided.

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 (non-readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine behavioral context beyond annotations by stating matching is deterministic and typos will not auto-launch a similar app, clarifying the failure mode.

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 short sentences, front-loaded with the core action and the exact-matching constraint. Every sentence earns its place 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description contributes the key determinism behavior, though it could mention prerequisites such as resolving the app via apple_tv_list_apps.

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 parameter is fully documented in the schema itself. The description restates 'exact bundle ID or exact display name' but adds no syntax or format detail beyond that, 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 ('Launch') and resource ('an installed application'), which cleanly distinguishes it from siblings like apple_tv_open_url (URLs) and apple_tv_list_apps (enumeration). It does not explicitly name a sibling to route against, so it falls just short of the top mark.

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 it (launching an installed app) but gives no explicit when/when-not guidance or pointers to alternatives such as using apple_tv_list_apps first to resolve a valid bundle ID. Usage context is only implied.

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 mark this as non-read-only, non-idempotent, and non-destructive, and the description adds genuinely useful context beyond that: a success only means the launch request was accepted, not that a screen is visible, and uncertain deliveries are deliberately not retried because of playback side effects. That side-effect and retry-semantics disclosure is exactly the kind of behavioral detail annotations cannot carry.

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 the action and followed by the two caveats that matter. No filler, though the sentences are line-broken in a way that reads slightly disjointed rather than as a single tight block.

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, and the description correctly manages expectations about what success means. The one remaining gap is the absence of any pointer to apple_tv_open_app for the non-deep-link case, which matters in a 13-tool sibling set.

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

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

Schema description coverage is 100% and the single url parameter is documented as accepting custom schemes. The description adds no format examples or scheme constraints 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 specific verb and resource (open a URL or application deep link on the Apple TV), which is unambiguous on its own. It does not explicitly contrast itself with the adjacent sibling apple_tv_open_app, so an agent must infer the URL-vs-app distinction from the parameter 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?

There is no explicit when-to-use, when-not-to-use, or named alternative. The note about deep links not being retried is a behavioral caveat rather than routing guidance, and the agent is never told to prefer apple_tv_open_app for plain app launches.

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, idempotentHint=false, destructiveHint=false). The description adds no behavioral context beyond the action list; the useful 'toggle/next/previous are not retried' note lives in the schema, not the description, so nothing here enriches the annotation coverage.

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 that names the resource and lists the actions with zero 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?

An output schema exists so return values need not be explained, and a 1-param tool is inherently simple. But the omission of sibling differentiation (especially versus apple_tv_skip) leaves a real navigational gap for an agent choosing among 14 playback-related tools.

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 enum parameter is fully documented in the schema, so the baseline is 3. The description merely restates the same enum values, adding no syntax, ordering, or 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?

States a specific verb ('Control playback') and enumerates the six actions, so an agent knows exactly what it does. However, it does not differentiate from siblings like apple_tv_skip, which overlaps with the 'next'/'previous' actions, leaving ambiguity between 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 lists allowed actions but gives no when-to-use guidance, no conditions selecting this tool over alternatives, and no exclusions. The overlap with apple_tv_skip is left unresolved, so the agent must infer when this 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 this is a non-read-only, non-destructive, non-idempotent operation, so the safety profile is covered. The description adds that it reports the observed power state, but says nothing about whether it waits for the state to settle, what happens on failure, or any device-permission requirements.

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 no filler; the action and the reporting behavior are both stated economically and nothing is 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?

An output schema exists, so return values need not be spelled out, and the lone parameter is fully documented. The definition is nearly sufficient, with the only gap being the absence of any note on how the observed state is confirmed or what failure looks like.

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

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

Schema description coverage is 100% and the single 'state' parameter is documented with a PowerTarget type. The description's 'on or off' mirrors the enum rather than adding new meaning, so baseline 3 applies.

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

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

Specific verb+resource: it sets the Apple TV power state and reports the observed result, which is clear and distinct from the sibling apple_tv_status (read-only) and playback/volume tools. It does not, however, explicitly name or contrast itself with apple_tv_status, so an agent must infer the boundary.

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?

There is no when-to-use/when-not guidance and no pointer to apple_tv_status for reading only. Usage is only implied by the 'on or off' phrasing, leaving the agent to guess whether this is preferable to apple_tv_status for state queries.

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

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

Annotations already declare idempotentHint=false and readOnlyHint=false, but the description adds genuinely new context: presses have no visual feedback, do not report focus, and are not auto-retried on uncertain failures. That is material for an agent planning a navigation sequence.

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 purpose followed by behavioral caveats and an alternative tool, with no filler. The two sentences about lacking visual feedback and not reporting focus overlap slightly, but overall it is 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?

With an output schema present and annotations covering the safety profile, the description need not explain return values; it instead supplies the operational caveats (no focus reporting, no retries) an agent needs. What remains unstated is how the non-idempotent navigation interacts with the count parameter.

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% with documented count, action, and button fields, so the schema already carries parameter meaning. The description adds nothing about button/action semantics beyond what is in the schema, making 3 the appropriate baseline.

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

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

States a specific verb and resource ('Press a remote button'), which is unambiguous and distinct from the playback/seek/skip siblings. It does not, however, enumerate the button set in prose, leaving that to 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?

Explicitly routes the agent to apple_tv_screenshot when visible UI state must be inspected or verified, and warns that uncertain transport failures are not retried automatically. It gives no guidance on when to prefer other navigation siblings (seek, skip, playback) over pressing.

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/idempotent/non-destructive, yet the description adds real behavioral context beyond them: the capture is a frozen snapshot that can go stale, DRM-protected video may render black while surrounding UI stays visible, and the tool depends on an optional screen-capture helper whose absence is reported rather than silently failing. These are exactly the caveats an agent needs 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?

The primary action is front-loaded in the first sentence, and the following sentences each cover a distinct failure/interpretation case (staleness, DRM black regions, missing helper). It is mildly longer than strictly necessary for a no-argument tool, but no sentence is filler.

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

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

Given no output schema, the description carries the return-value burden well by stating the result is a single PNG and by pre-empting the two most likely misreadings (stale capture, black DRM region). It also discloses the helper dependency, so an agent knows what an unavailable-capture response means.

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 schema coverage is 100%, so per the baseline no parameter guidance is required. The description correctly adds nothing about arguments and instead spends its words on output interpretation.

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

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

The first sentence states a specific verb and resource ('Capture the Apple TV screen') plus the output form ('one PNG image'), which is unique among siblings that otherwise control playback, volume, power, or apps. An agent can distinguish it from every sibling without opening a 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 supplies clear usage context: 'point-in-time evidence of what the Apple TV rendered when the capture ran' and 'capture again to verify' after later actions. It does not name an alternative tool or state when-not to use it, but with no sibling offering similar functionality there is little to exclude.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, covering the safety profile. The description adds the useful 'absolute position' framing versus relative seeks, but does not say whether the video must be playing, whether seeking preserves play state, or anything beyond the 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?

A single tightly-scoped sentence with zero filler, and the key concept ('absolute') 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 single-parameter tool with full schema coverage, an output schema, and safety annotations, the definition is nearly sufficient. The main missing piece is routing versus the relative apple_tv_skip sibling, but no return-value explanation is needed given the output schema.

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

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

Schema description coverage is 100%, so the single parameter is already documented with type, minimum, and meaning. The description merely restates the schema's 'Absolute playback position in seconds' phrasing and adds no new 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?

States a specific verb (seek) and resource (playback position) plus the unit (seconds). It distinguishes itself from the relative-motion sibling apple_tv_skip by specifying 'absolute', though it doesn't name that sibling explicitly.

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?

There is no explicit when-to-use guidance and no mention of the alternative apple_tv_skip for relative seeking. The agent must infer that 'absolute' position implies this over the relative skip tool.

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

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

Annotations already declare it non-read-only, idempotent and non-destructive; the description adds genuine context beyond that by stating the virtual-keyboard precondition and that an empty string clears the field — a behavior an agent could otherwise trigger by accident. It does not say what happens if no keyboard is focused (error vs no-op).

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 short sentences, front-loaded with the action, followed by the precondition and the edge case. 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?

An output schema exists, so return values need not be described, and the mutation semantics, precondition and empty-string behavior are covered. The only real gap is failure behavior when the precondition is unmet.

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% for the single parameter, and the property description already says 'Empty string clears it.' The description restates that same fact rather than adding format or length constraints, so the schema is doing the work.

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 ('Replace text in a focused Apple TV text field'), making it immediately distinguishable from the press/seek/playback siblings. An agent can tell this is the text-entry tool without reading any 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 a clear precondition for use ('Requires an active virtual keyboard') and the edge-case semantic for an empty string. It does not name an alternative (e.g. apple_tv_press for individual key presses), so it stops short of full routing guidance.

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

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

Annotations already declare this is a non-destructive, idempotent write (readOnlyHint=false, idempotentHint=true, destructiveHint=false), consistent with setting an absolute value. The description's added value is the capability precondition ('when the device supports volume control'), but it says nothing about failure behavior when unsupported or whether the call blocks.

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 efficient sentence with the operation front-loaded and the capability condition trailing. Nothing is wasted, though it is arguably a touch sparse for a routing-sensitive volume tool.

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

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

With a simple one-parameter schema, an output schema present, and annotations covering the safety profile, the description supplies the essential capability caveat. The only meaningful omission is disambiguation from apple_tv_adjust_volume.

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 parameter is fully documented with a 0-100 range and 'Absolute volume percent' description. The tool description adds no syntax, unit, or boundary detail beyond what the schema already provides, 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?

The description states a specific verb and resource ('Set absolute volume percent'), immediately conveying the operation. 'Absolute' implicitly contrasts with the relative sibling apple_tv_adjust_volume, but that sibling is never named, so an agent must infer the distinction itself.

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 one condition for use ('when the device supports volume control'), which is useful gating context. However, it never names apple_tv_adjust_volume as the alternative for relative changes, leaving the key routing decision (absolute vs. relative volume) 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 declare destructiveHint=false and idempotentHint=false, but the description adds a genuinely non-obvious trait: relative skips are not retried after uncertain failure. That retry/failure semantic is not derivable from the annotations or schema and materially affects how an agent should handle errors.

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 short sentences, purpose front-loaded and the caveat second. 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?

An output schema exists, so return values need not be explained, and the retry caveat covers the main behavioral risk. However, with apple_tv_seek as a direct sibling, the definition never clarifies which one to call, leaving a real routing gap.

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

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

Schema description coverage is 100%, so both parameters are already documented, including that seconds=0 lets the device pick a default. The description adds no syntax or constraint detail 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?

The description names a specific verb+resource ('Skip forward or backward') and the phrase 'Relative skips' signals this is a relative-position operation. It does not explicitly name apple_tv_seek as the absolute-position alternative, so the sibling distinction is only implied.

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?

There is no explicit when-to-use guidance and no mention of apple_tv_seek, the obvious alternative for absolute jumps. The agent must infer the relative-vs-absolute split from the word 'Relative' alone.

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 safety is covered; the description adds real behavioral context beyond them by stating that media_app does not guarantee foreground/visible application and that status does not capture the screen. It does not describe refresh timing or determinism of the snapshot, which would be the next useful detail.

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 what is read in the first clause, then spends the remaining two sentences on the two cases most likely to cause misuse (media_app semantics, screen capture). 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?

An output schema exists, so return-value documentation is not required, and the description covers purpose, one clear alternative, and the key field caveat. It stops short of stating the freshness/cost of the read or how it relates to the other state-mutating siblings, which is a minor gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description still adds meaning about a returned field (media_app), which is more than the empty input schema conveys.

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 (Read) and resource (current device/power/playback/volume/keyboard state), and enumerates the state domains covered so an agent can distinguish it from apple_tv_power, apple_tv_playback, or apple_tv_set_volume. It explicitly names apple_tv_screenshot as the sibling for a different need.

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-else clause: for rendered screen content, use apple_tv_screenshot instead. It also clarifies that media_app is not a foreground-app indicator, steering the agent away from a wrong inference. It does not cover the other read-ish siblings (capabilities, list_apps), but the main boundary is drawn.

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