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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real value beyond them: the SSDP mechanism, the ~3 second blocking duration, and a prompt-injection warning to treat returned server strings as data rather than instructions — an important behavioral caveat for a network-facing tool.

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 with zero filler. The operation, cost (3 seconds), and security caveat are all 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?

An output schema exists, so return values need not be described. The description covers mechanism, timing, and the untrusted-data caveat — enough for correct invocation — though it omits any hint about what follows discovery (pairing).

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 clarify; the baseline for a no-arg tool 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 (scan), resource (local network for LG webOS TVs), protocol (SSDP) and duration (~3 seconds). This clearly separates it from list_tvs, which implies enumerating already-known/paired devices rather than actively discovering new ones.

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 a pre-pairing discovery step, but the description never states when to use it versus list_tvs or whether it must precede pair_tv. No explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is partly covered, but the description adds a genuinely useful behavioral warning: TV-supplied names should be treated as data, not instructions, which is prompt-injection guidance an agent could not derive from the schema. It does not mention errors when no TV is paired or unreachable, so it is 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?

Two tightly written sentences: the return contents are front-loaded in an enumerated list, followed by one imperative safety clause. No padding or restatement of the name.

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 read-only profile; the description adds the injection caveat and the scope of state covered. It omits fallback behavior when no TV is paired, which is a minor gap for a zero-required-parameter 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% and the single optional `tv` parameter is already documented in the schema ('Omit to use the default TV'). The description adds nothing about the parameter, 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 precisely what the tool reads back — power state, app/input, live-TV channel and program, volume, mute, sound output — which lets an agent distinguish it from list_apps, list_inputs and get_tv_info. The verb is implied by the name rather than stated, and no sibling is named explicitly, so it falls just short of full differentiation.

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 statement of when to call this versus get_tv_info, list_tvs, or the many setter siblings (set_volume, set_mute, switch_input). Usage is only inferable from the fact that it is a read operation, with no prerequisites or exclusions 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=true and openWorldHint=false, so safety is covered. The description usefully enumerates the returned fields (model, webOS version, network address), adding context beyond the annotations, but says nothing about the default-TV fallback or failure modes.

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?

One short, front-loaded fragment with zero padding. It is efficient, though its brevity is partly a function of under-specification rather than tight editing.

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 the description need not explain return values, and the annotations cover the safety profile. However, for a tool surrounded by many related TV/status siblings, the description alone gives no routing or contextual guidance.

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 'tv' parameter is already documented, including the 'omit to use the default TV' behavior. The description adds no further 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?

The description names the specific data the tool retrieves (model, webOS version, network address) but is a noun fragment with no verb and does not distinguish itself from adjacent siblings like get_status or list_tvs. The purpose is inferable but not crisply stated.

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 guidance on when to call this tool versus get_status, list_tvs, or pair_tv_status. The agent must infer usage entirely from the field list.

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 only declare the safety profile (not read-only, non-destructive, closed-world). The description adds genuinely behavioral detail beyond that: loose name matching and the fact that ambiguous names return a list of options instead of launching. It omits what happens on a completely unmatched name, so not a 5.

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 immediately by the one non-obvious behavioral caveat. 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 no explanation, and annotations cover safety. The ambiguity-handling note covers the main failure mode an agent would hit; only the unknown-name case is left unstated.

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 schema already documents both 'name' and 'tv' (including the default-TV behavior). The description nonetheless adds matching semantics for 'name' – loose matching and ambiguity resolution – which the schema 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?

States a specific verb and resource ('Open an app'), which clearly separates it from siblings like list_apps and play_youtube. It does not, however, explicitly name any alternative action tool, so it stops short of full sibling differentiation.

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 purpose – the agent infers it should call this to launch rather than enumerate apps. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., play_youtube for content playback), so guidance is minimal.

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 safety profile is covered. The description adds a genuinely useful non-obvious trait: titles originate from the TV and must be treated as data, not instructions — a prompt-injection caveat worth surfacing.

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 clauses with zero padding, and the resource statement is front-loaded. It's a fragment rather than a sentence, but nothing is wasted.

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 needn't be explained, and annotations cover safety. What's missing is usage framing — when this list should be consulted versus other discovery tools like list_tvs or get_tv_info — leaving a modest 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% and the single tv parameter is fully documented in the schema (paired TV name, omit for default). The description adds nothing about the selector, 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 the resource ('installed apps') and the returned fields (title, id), which is a clear listing operation. It doesn't explicitly contrast with siblings like launch_app or play_youtube, but the 'installed apps' scope is unambiguous enough for selection.

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?

No when-to-use or when-not-to-use guidance is given. The reader must infer that this is a discovery step preceding launch_app, and the description says nothing about the optional tv selector behavior beyond what the schema already documents.

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 readOnlyHint and openWorldHint, so the safety profile is set. The description adds genuinely non-obvious behavioral context: that labels originate from the TV and should be treated as data rather than instructions, which is meaningful prompt-injection guidance, plus the connected-device state included in 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 first states what is returned and the second delivers the one non-obvious caution. Nothing is wasted and the payload summary 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?

With an output schema present, return-value explanation is not required, and the description still covers content plus a security-relevant caveat. It is only short of complete because it omits any routing hint toward sibling input-mutating tools like switch_input.

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 already explains that omitting 'tv' uses the default TV. The description adds nothing about the parameter, so the baseline 3 applies since the schema carries the load.

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 the resource and enumerates what is returned (label, id, connected-device flag), so an agent knows this reads the TV's available input list. It stops short of a direct verb and never contrasts itself with the obvious sibling switch_input, which is about changing inputs rather than listing them.

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 statement of when to call this versus alternatives such as switch_input or get_tv_info, and no prerequisite or context given. The agent must infer usage from the name 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 the safety profile is covered. The description adds the useful detail that the default TV is surfaced, but says nothing about ordering, whether unpaired TVs appear, or freshness of the listing.

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?

One short, front-loaded sentence with no filler. Every clause earns its place by naming the resource and the distinguishing return 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?

With no parameters, an output schema covering return values, and annotations covering the safety profile, the only missing piece is routing guidance against siblings such as discover_tvs. The description is otherwise sufficient 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?

The tool takes zero parameters, so there is nothing for the description to compensate for; baseline for a no-arg tool is 4.

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

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

States a specific verb (List) and resource (paired TVs), plus an extra detail (which one is the default) that tells the agent the return content. It does not explicitly differentiate itself from the sibling discover_tvs, but 'paired' vs discovery scope is strongly 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?

Usage is only implied: an agent can infer this is the tool for inspecting already-paired TVs. There is no explicit statement of when to use this versus discover_tvs (for finding new TVs) or get_tv_info (for details on one TV).

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 tool is not read-only and has destructive potential. The description adds useful non-annotation context: the operation is asynchronous, returns immediately, requires a human to accept on the TV with a remote, and must be followed by polling pair_tv_status. It does not explain the destructive overwrite behavior (covered by the replace parameter and destructiveHint).

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 essential behavioral details. 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?

An output schema exists, so return values need not be described. The description covers the asynchronous initiation and required follow-up polling, which are critical for correct invocation. Minor edge cases (timeouts, already-paired behavior) are left to the schema and annotations.

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 every parameter is fully documented in the schema. The description adds no parameter-level details, so the baseline score of 3 is appropriate.

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

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

The description begins with a specific verb+resource ("Start pairing with a TV") and explains the core interaction (prompt on TV, remote acceptance). It also distinguishes itself from the sibling tool pair_tv_status by naming it as the follow-up poll target.

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

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

It clearly indicates the tool's role as the initiation step and points the agent to pair_tv_status for subsequent polling. However, it does not explicitly state when *not* to use it (e.g., if already paired) or name alternative approaches beyond the polling sibling.

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 safety profile is covered. The description adds the enumerable outcome states (waiting, paired, failed), which is useful behavioral context, but since an output schema exists those states are likely documented there and no polling or failure-handling behavior is explained.

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 pairing linkage and the possible outcomes are both conveyed compactly.

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, single-parameter polling tool with full schema coverage, explicit read-only annotations, and an output schema covering return values, the description supplies everything an agent needs to call it correctly. Only polling cadence/termination guidance is absent, which is minor.

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 "name" parameter is already documented as "Name used in pair_tv." The description adds no format, constraint, or matching 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 specific verb ("Check") and resource (a pairing) and anchors it to the sibling that creates the pairing ("started with pair_tv"), which cleanly separates it from get_status. An agent can pick between the two 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?

The phrase "started with pair_tv" clearly implies the workflow context: call this after pair_tv to poll the pairing outcome. It gives no explicit exclusions or timing guidance (e.g. how often to poll), so it stops short of a 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 readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a non-destructive local-network action. The description adds one useful behavioral detail, that a t= start time is honored, but does not disclose what happens to currently playing content or any failure modes.

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 purpose comes first and the start-time caveat is a brief trailing clause.

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 documented, and annotations cover the safety profile. The only real gap is prerequisite/alternative routing (paired TV, launch_app overlap), which is minor for a two-parameter 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% and both parameters are described there (tv default behavior, accepted URL forms and 11-char id). The description's 't= start time' clause adds a small amount of meaning beyond the schema, matching the baseline-3 case where the schema does the heavy lifting.

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: 'Play a YouTube video on the TV', which is meaningfully distinct from the generic launch_app sibling. It also notes the t= start-time handling. It does not explicitly name which sibling it should be preferred over, so it stops 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?

Usage is implied by the purpose text but there is no explicit when-to-use guidance, no exclusion for launch_app (which could also open YouTube), and no mention of prerequisites such as a paired TV being required.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact — power-on may use network wake-up or Wake-on-LAN, implying the TV can be off/remote — but says nothing about latency, permission/pairing requirements, or side effects of powering off.

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 tight sentence with the action front-loaded and the mechanism as a brief parenthetical. No waste.

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 annotations carry the safety profile. Still, for a mutation tool that powers a device on/off, the description omits pairing prerequisites and any note that a remote wake may fail or be delayed.

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 'tv' parameter is documented in the schema but the required 'state' enum has no description there. The description's 'on or off' loosely mirrors the enum but adds no format, defaulting, or targeting guidance to compensate for the coverage gap.

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 (turn on/off) and resource (TV), plus the wake mechanism used. It is clearly distinguishable from volume/input/app siblings, though it never names them 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?

No when-to-use, prerequisites, or alternatives are given. The parenthetical 'network wake-up or Wake-on-LAN' hints at mechanism but not at when this tool is the right choice over e.g. get_status or pair_tv.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no mention that keys are delivered sequentially with timing, no auth/pairing requirement, no side-effect 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?

A single short, front-loaded sentence with zero padding. It is concise, though the terseness borders on under-specification rather than deliberate economy.

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 parameters are fully documented in the schema. However, for a write-ish device-control tool, the description leaves out ordering/timing behavior and the pairing dependency, which are material to correct invocation.

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

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

Schema description coverage is 100%: the keys parameter lists accepted values and example ordering, and tv explains the default-TV behavior. The description adds nothing 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 (press) and resource (remote control buttons), so an agent knows exactly the action being taken. It does not differentiate from siblings that also emit remote commands (power, set_volume, set_mute, launch_app), so it falls 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?

There is no when-to-use guidance, no mention of prerequisites (paired TV), and no routing to sibling tools that cover common buttons like power, volume, or mute. The agent must infer that raw navigation keys are this tool's domain.

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, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds nothing beyond that: it does not clarify whether this sets an absolute mute state or toggles, nor what happens if no paired TV exists, which is the key ambiguity for a state setter.

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 six-word sentence with no filler, front-loading the operation. It is appropriately sized, though its brevity is a symptom of missing substance rather than disciplined editing.

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 tool is simple with two parameters. However, the description omits the state-setting semantics and the default-TV behavior, leaving meaningful gaps for an agent invoking a mutation.

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 only 50% – the tv parameter is documented in-schema while the required muted boolean has no description. The phrase 'mute or unmute' loosely hints at the boolean meaning but does not compensate for the missing parameter documentation or explain the default-TV fallback.

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 pair (mute/unmute) and resource (TV), so the operation is immediately understandable. It does not differentiate itself from sibling tools like set_volume or get_status, but the verb+resource 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?

There is no guidance on when to use this versus set_volume or other TV-control siblings, and no stated prerequisites (e.g., a paired TV must exist). The agent must infer usage context entirely.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds a genuine behavioral trait beyond annotations – audio keeps playing when the picture is off – but says nothing about state persistence, restoration, or error conditions for an unpairable TV.

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 tight sentence that front-loads the action and the key constraint. Nothing is wasted and no padding exists.

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 mutation safety profile. For a simple two-parameter toggle the description is nearly complete; only the interaction with the 'power' sibling and TV-selection behavior remain 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%, so both parameters ('on' and 'tv') are already fully documented in the schema, including the note that false blanks the picture while sound continues and that omitting 'tv' uses the default. The description adds no parameter detail beyond this, making the baseline 3 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+resource (turn the picture on/off) and adds the distinguishing scope 'without affecting sound', which separates it from the sibling 'power' tool that presumably toggles the whole TV. However, it does not name the sibling it differs from, so the differentiation must be inferred.

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 by the phrase 'without affecting sound' – an agent can infer this is the right tool when audio must keep playing while the display blanks. No explicit when-to-use, when-not-to-use, or named alternative (e.g., 'power') 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?

Reveals a significant side effect beyond annotations: the TV's pairing key will be sent to the new address, which explains the destructive hint and justifies the user-confirmation requirement. It does not cover failure modes or whether the TV must be online, but adds valuable behavioral context that annotations alone do not provide.

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

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

Two tightly written sentences with zero filler. The purpose is front-loaded, followed by a critical usage caveat, making it 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?

Output schema exists, so return values need no explanation. Annotations cover safety profile, and the description supplies the key operational context (when to call, what data is transmitted). Complete for a two-parameter update 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 both parameters (name and host) have clear schema descriptions. The tool description adds no parameter-level details beyond what the schema already provides, 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 (Update) and resource (paired TV's IP address) with a clear condition (after it changed). Distinguishes from siblings like pair_tv, list_tvs, and discover_tvs, which handle different lifecycle stages.

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 'only call this when the user confirms it is their TV,' giving a clear when-to-call guard. However, it does not name alternatives (e.g., pair_tv for unpaired TVs or discover_tvs for finding TVs), so it stops short of full alternative routing.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful mutual-exclusivity constraint ('Give exactly one') beyond the schema, but says nothing about failure behavior when the TV is unpaired or unreachable.

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, zero filler, with the core action and the argument rule front-loaded. Nothing here could be cut 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?

An output schema exists, so return values need no explanation, and annotations cover the mutation safety profile. The description is close to sufficient, but a one-clause note on what happens with an invalid target TV would make it fully self-contained.

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, and the description genuinely adds the cross-parameter rule that exactly one of level/step may be provided — a constraint the schema's nullable defaults do not express. That extra constraint earns a step above 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?

The description states a specific verb and resource ('Set the volume') plus the two accepted modes of setting it, so an agent immediately knows what the tool does. It does not explicitly distinguish itself from near-neighbors such as set_mute, 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?

'Give exactly one' tells the agent how to supply arguments, which is real invocation guidance. It says nothing about when to prefer this over set_mute or when a relative step is better than an absolute level, so 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 already declare destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the output is a transient toast, but does not disclose duration, whether it queues or replaces an existing message, or what happens if no TV is reachable.

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 wasted words; the noun phrase 'short notification (toast)' efficiently conveys both the effect and its transient nature.

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 a full output schema and clear annotations, the description is nearly sufficient. Only minor gaps remain (display duration, behavior on delivery failure), which are unlikely to block correct invocation.

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

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

Schema description coverage is 100%, including the fallback semantics of the optional 'tv' parameter ('Omit to use the default TV') and the 1-200 character bounds on 'text'. The description adds nothing 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 (Show) and resource (short notification/toast on the TV screen), which is distinct from siblings like launch_app, play_youtube, or set_screen. It is clear what the tool does, though it never names or contrasts against any sibling tool.

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

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

The phrase 'short notification (toast)' implies transient, user-facing messaging use, but there is no explicit when-to-use, when-not-to-use, or routing to an alternative (e.g., set_screen) for persistent text.

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, destructiveHint=false and openWorldHint=false, carrying the safety profile. The description adds one genuine behavioral trait beyond the annotations: names are matched loosely, which affects invocation success. It does not disclose side effects of switching or handling of invalid names.

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, with no filler. It is efficient, though arguably terse enough to leave gaps that concise structure cannot excuse.

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. However, for a state-changing tool with a loosely-matched identifier, the description omits what happens on ambiguous or failed matches and how it relates to list_inputs.

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 name and tv parameters are already documented (including the 'HDMI 2'/'PS5' example and the default-TV behavior), setting the baseline at 3. 'Names are matched loosely' adds a small amount of matching semantics to the name parameter but nothing beyond that.

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 ('Switch to an input'), so an agent immediately knows this changes the active input. It does not explicitly differentiate from the sibling list_inputs, which handles the same resource, leaving the switch-vs-list distinction to inference.

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 guidance, no prerequisites, and no mention of alternatives such as list_inputs for discovering valid names. The only sentence beyond the purpose is a matching note, not usage context.

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