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

The description adds genuinely useful operational context beyond annotations: UDP port 65001, the VLAN limitation, and the three transport variants. However, annotations declare readOnlyHint=false and idempotentHint=false, and the description never explains what state is written or why a discovery operation is not read-only — the "Cache" name implies persistence that is never described.

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

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

Two sentences, no padding, but the lead "Cache (discovery_operations)" is opaque and front-loads the confusing term, and the trailing "CONCEPT:HDHR-discovery.network.device-location" tag is internal taxonomy that gives the agent nothing actionable.

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. But for a parameterless, non-idempotent, non-read-only tool whose name is "Cache" and whose siblings already cover each discovery mode, the description leaves the central questions unanswered: what is cached, when is it refreshed, and why use this instead of the granular discover 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?

With zero parameters, the baseline is 4, but the description creates a mismatch by describing "targeted UDP to a known IP" as an available mode when the schema exposes no way to supply that IP. That unexplained inconsistency lowers the score below the parameterless 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 recognizable verb and resource ("Discover HDHomeRun devices on the network") and lists the three discovery mechanisms, but it never reconciles the name/title "Cache" with the discovery framing. It also fails to distinguish itself from the dedicated siblings hdhomerun_discover_local_broadcast, hdhomerun_discover_local_targeted, and hdhomerun_discover_cloud, which appear to do exactly the sub-operations named here.

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 versus the three per-method discovery siblings, nor on when to re-run it versus reading a cached result. The closest thing to guidance is the parenthetical "may not cross VLANs", which is a caveat rather than a routing rule.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP verb/path, which confirms this is a mutating POST, but it does not say what happens when no scan is running (error vs. no-op) or whether the abort takes effect immediately.

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 sentence with the operation front-loaded and zero filler; the endpoint is appended rather than leading.

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

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

For a zero-argument mutation whose annotations already carry the safety and idempotency profile, the description is essentially sufficient. The only real gap is the no-scan-in-progress outcome, which an agent might reasonably want to know.

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 to disambiguate and the baseline is 4. No parameter detail is needed or missing.

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?

Names a specific verb ('cancel') and resource ('an in-progress channel scan'), and the included endpoint string confirms the underlying operation. It is clearly distinguishable from hdhomerun_start_scan, though it does not 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?

The 'in-progress' qualifier implies when the tool applies, and the start_scan sibling makes the alternative obvious by inference. However, there is no explicit statement of prerequisites, when-not-to-use, or what to call instead.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description need only add context. It contributes the rule kind and its effect ('record one specific airing') but says nothing about collisions with existing rules, permissions/device_auth, or reversibility.

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 key qualifier front-loaded and no filler. Brevity is appropriate, though it leaves too much unsaid for a 6-parameter mutation.

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

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

For a mutation tool with no output schema, 0% param coverage, and domain-specific integer/time semantics, the definition is too thin. An agent still lacks the format of date_time_only, the role of series_id, auth requirements, and padding behavior.

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

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

With 0% schema coverage across 6 parameters, the description must carry all meaning, yet it only names two of them implicitly via 'DateTimeOnly-ChannelOnly'. It omits the date_time_only integer format (epoch? timestamp?), series_id, device_auth, and the start/end padding 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 (Add) and resource (a DateTimeOnly-ChannelOnly rule) and clarifies with the parenthetical 'record one specific airing'. This distinguishes it semantically from the sibling add_series_rule, though it never names 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?

The phrase 'record one specific airing' implies when this tool applies (a single airing versus a recurring series), giving usable context. But there is no explicit when/when-not, no mention of add_series_rule as the alternative, and no prerequisites such as device_auth.

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=true, so the mutation/safety profile is covered. The description adds nothing beyond that: it does not say what happens on a duplicate rule, whether auth is needed, whether the rule takes effect immediately, or how it interacts with existing rules.

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

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

The single sentence is front-loaded and free of waste, but its brevity comes from omitting content rather than being efficiently written. It is concise without being informative.

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 an 8-parameter mutation tool with 0% schema coverage and no output schema, the description is far too thin. An agent would have to guess at padding units, channel/team filter semantics, and auth handling before it could call this correctly.

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

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

Schema description coverage is 0% across 8 parameters, and the description only implicitly names series_id. Every other parameter (team_only, device_auth, end_padding, recent_only, channel_only, start_padding, after_original_airdate_only) is left completely undocumented in both the schema and the description.

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: 'Add a Series (or Movie) recording rule', keyed by SeriesID. This is enough to distinguish it from siblings like hdhomerun_add_datetime_rule and hdhomerun_change_rule without opening the schema, though the sibling differentiation is only implied, not 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 use this versus hdhomerun_add_datetime_rule, hdhomerun_change_rule, or hdhomerun_list_recording_rules. No prerequisites (e.g., whether device_auth or a reachable device is required) are mentioned, so the agent must infer invocation conditions 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuine behavioral context about session identity semantics and seeking reuse, but omits any auth requirements, rate limits, or what the resulting URL looks like. The reference to the 'live_tv doc page' pushes detail off-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, front-loaded with the core action and followed by the identity constraints that matter most. Minor waste in the trailing doc-page pointer, but 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?

No output schema and 0% schema coverage mean the description should be more self-sufficient. It explains session identity well but leaves channel format, base URL expectations, and any notion of what the returned URL is (fmt/transcode params?) undocumented — gaps an agent would hit immediately.

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

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

Schema description coverage is 0% with 4 required parameters, so the description must carry the load. It does meaningfully define client_id and session_id semantics (stability and uniqueness rules), but channel and storage_engine_base_url receive no explanation at all — no format, no source, no example.

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: 'Build a record-engine buffered Live TV URL.' The 'record-engine buffered' qualifier distinguishes it from a plain stream URL conceptually, but the sibling hdhomerun_build_stream_url is never named, so the agent must infer the boundary 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?

The description gives lifecycle rules (stable ClientID per app instance/PiP pane, unique SessionID per channel request except when seeking) which implies when to call, but never states explicitly when to use this versus hdhomerun_build_stream_url or other playback tools. Usage is inferable 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?

The description says this tool builds a URL, implying a pure string construction with no state change, while annotations set `readOnlyHint: false`. That conflicts with the apparent side-effect-free nature of the tool, and no further behavioral context (auth, stream start, return type) is disclosed.

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

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

The description is front-loaded with the URL template, then gives a clearly structured Args list. Every line adds usable detail and there is 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?

It covers the URL format and all parameters thoroughly, but with no output schema it should state what is returned, such as a URL string, and clarify whether it merely constructs the URL or also starts a stream. Those gaps matter given the annotation conflict.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well. It documents all six parameters: `channel` as virtual channel or RF frequency, `tuner` index or `None` for auto, `by_frequency` addressing mode, `program` only with `by_frequency`, `duration`, and `transcode`.

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?

It states a specific verb and resource: build a live-stream URL, and even gives the exact URL path template. The main gap is that it does not distinguish itself from the very similar sibling `hdhomerun_build_live_tv_url`.

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 explains parameter forms but gives no explicit when-to-use guidance, no alternatives, and no exclusion rules. An agent must infer when to choose this builder versus `hdhomerun_build_live_tv_url` or other streaming-related tools.

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=true, so the safety profile is covered; the description usefully adds that after_recording_rule_id reorders rules rather than editing content. However, for an 11-parameter mutation it says nothing about whether omitted/null fields are left unchanged or cleared, what permissions or device auth are needed, or whether changes are reversible.

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

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

The single sentence is front-loaded with the verb and wastes no words, which is good. But for a tool with eleven optional parameters and no schema descriptions, one sentence is under-sized for what the agent needs to know.

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

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

With no output schema, 0% parameter coverage and sparse annotations, the description should explain the parameter surface and the partial-update model; it does neither. It conveys the tool's identity and one semantic detail, but not enough for an agent to invoke it correctly on an arbitrary rule.

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

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

Schema description coverage is 0% across 11 parameters, so the description must carry the burden and it explains only after_recording_rule_id. series_id, team_only, channel_only, start_padding, end_padding, recent_only, date_time_only, after_original_airdate_only, recording_rule_id and device_auth remain completely undocumented in both schema and description.

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 ('Modify') and resource ('a rule'), and adds a distinct secondary mode ('reprioritize it via after_recording_rule_id') that separates it from the add_* and delete_* siblings. It does not explicitly name hdhomerun_add_series_rule or hdhomerun_delete_rule as the alternatives for create/remove, so sibling differentiation is only implicit.

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 statement of when to use this versus hdhomerun_add_series_rule, hdhomerun_add_datetime_rule, or hdhomerun_delete_rule, and no prerequisites (e.g. that an existing recording_rule_id is required, even though that parameter is optional in the schema). The reprioritization clause hints at one use case but gives no conditions or exclusions.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the description should explain that this is a non-read-only, network-touching operation (and why, e.g. cloud validation). It says nothing beyond the operation name, leaving the agent with no behavioral context.

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

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

It is brief, but brevity here is under-specification rather than conciseness — one empty sentence that could not be shorter without vanishing.

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, but purpose, the meaning of both parameters, and the cloud-vs-device auth distinction are entirely absent, making the definition unusable for correct invocation.

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

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

Schema description coverage is 0% for two parameters (info, validate_cloud) with opaque names, and the description adds no explanation of what 'info' should contain or what 'validate_cloud' triggers. Full compensation was required here and none was given.

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 is a tautology: 'Invoke the check_device_auth operation' merely restates the tool name and title without saying what device auth checking entails, what it inspects, or how it relates to siblings like hdhomerun_check_device_reachable or hdhomerun_get_lockkey.

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 guidance at all: nothing about when to check device auth, when to prefer the many check_* / get_* siblings, or any prerequisites. The single sentence offers no decision criteria.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, but the description adds zero context on top of them — no mention of what a 'reachable' check entails, network probing side effects, or timeouts. It contributes nothing beyond structured metadata.

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

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

The single sentence is short but vacuous — it is under-specification rather than conciseness. Nothing is front-loaded because nothing informative is present.

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?

Although an output schema exists (so return values needn't be explained), the description gives no clue what 'reachable' means, what device it targets, or how failure is reported. For a sibling set of dozens of similarly named check_* tools, this is inadequate.

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 no parameter semantics to document; the baseline for zero-param tools applies. The description neither helps nor hurts here.

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 merely restates the tool name ('check_device_reachable') as 'Invoke the check_device_reachable operation', adding no specific verb or resource detail. It does not distinguish this from siblings like hdhomerun_check_device_auth or hdhomerun_check_signal_strength.

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 indication of when to use this tool, when not to, or which sibling alternatives exist. The agent is left to guess based on 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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, which is counterintuitive for a 'check' operation, yet the description adds nothing to clarify what mutation or side effect occurs. It repeats the annotation title verbatim rather than explaining behavior, so it earns no credit beyond the structured fields.

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

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

A single short sentence, but its brevity comes from under-specification rather than efficiency. The one sentence present conveys no information an agent could not get from the tool name, so it does not earn its place.

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

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

Despite an output schema existing, an agent still cannot tell what the cache is, what 'freshness' measures, why the operation is marked non-read-only and open-world, or how it relates to discovery_operations_cache. For a tool with a surprising annotation profile, this description is wholly inadequate.

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

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

The tool takes zero parameters, and the description makes no false claims about inputs. With no parameters to document, there is nothing the description could add, so the baseline for a zero-param 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?

The description restates the tool name/title as 'Invoke the check_discovery_cache_freshness operation' without saying what is actually checked, what 'freshness' means, or what happens as a result. It is essentially a tautology and gives no differentiation from siblings like discovery_operations_cache or hdhomerun_get_discover.

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 guidance on when to call this versus the many discovery-related siblings (discovery_operations_cache, hdhomerun_discover_cloud, hdhomerun_discover_local_broadcast, hdhomerun_get_discover). No prerequisites, no exclusions, nothing an agent could use to choose this 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 declare readOnlyHint=false and openWorldHint=true, meaning this is a non-read, open-world call, but the description explains none of that—no mention of device contact, network access, or side effects. The description adds zero behavioral context beyond the annotations and is silent on the unusual fact that a "check" is flagged as not read-only.

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?

It is short, but the brevity comes from under-specification rather than efficiency—the single sentence carries no information an agent could 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?

Even though an output schema exists (reducing the need to describe returns), the tool has an undocumented free-form parameter and non-read-only, open-world annotations; the description covers none of this and is nowhere near sufficient.

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

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

Schema description coverage is 0% for the single parameter "info", an untyped anyOf object with no documented shape or purpose. The description provides no compensation whatsoever, leaving the agent unable to know what to supply.

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?

"Invoke the check_firmware_model operation" restates the tool name without saying what the operation actually does—no verb describing the effect on firmware/model data, no scope, no outcome. An agent cannot distinguish this from the many sibling check_* / get_sys_* tools based on this text 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 when-to-use guidance, no prerequisites, and no mention of any alternative such as hdhomerun_get_sys_model or hdhomerun_get_sys_version, which appear to overlap with 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=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful behavior beyond that: it says the tool briefly tunes each channel, samples ss/snq/seq, and releases the tuner. However, it does not explain the transient tuner occupancy, failure behavior if a tuner is busy, or what happens when multiple channels are requested on one tuner.

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

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

A single sentence that front-loads the core sequence: tune, sample, release. It is efficient, though the ss/snq/seq abbreviations are unexplained jargon that may not be self-evident without domain knowledge.

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. But with two parameters at 0% schema coverage and no annotation-level detail about tuner contention or channel format, the description leaves important gaps for a hardware-interacting tool. It explains the high-level flow but not enough to invoke it confidently.

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

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

Schema description coverage is 0%, so the description must carry the burden. It implies that channels is a list of channel identifiers to tune and sample, but it says nothing about accepted channel formats, the meaning of the tuner index, or defaults. The tuner parameter is completely unaddressed.

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

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

The description gives a concrete behavior: tune each channel, sample ss/snq/seq, release the tuner. That is a clear, specific operation distinct from adjacent tools like hdhomerun_get_tuner_status or hdhomerun_get_tuner_vstatus, which inspect state rather than actively measure channels. It stops short of a 5 because it never states the purpose in outcome terms (signal quality assessment) and does not explicitly name a sibling it differs from.

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 about when to use this versus hdhomerun_get_tuner_status, hdhomerun_get_tuner_vstatus, hdhomerun_get_tuner_streaminfo, or hdhomerun_run_doctor. It also omits prerequisites such as needing a free tuner or authenticated device access. The only implied usage cue is that channels must be supplied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing on top of that: no mention that it contacts an external Jellyfin server, what auth/credentials are required, whether the comparison can fail, or what kind of discrepancy it reports.

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?

It is a single short sentence with no padding, but that brevity reflects under-specification rather than conciseness of content. Nothing is front-loaded because there is nothing substantive to front-load.

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, but the tool requires two credentials and an external service call — none of that operational context is present. For a cross-system check with 4 undocumented params, this description leaves the agent without enough to call it confidently.

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?

Four parameters with 0% schema description coverage, and the description provides zero parameter semantics. The required jellyfin_url and jellyfin_api_key, plus device_id and info, are completely undocumented — the agent cannot know which device is compared, what 'info' should contain, or what form the API key takes.

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 is a tautology: 'Invoke the check_tuner_count_vs_jellyfin operation' only restates the tool name and title. It adds no verb+resource specification beyond what the identifier already implies, and gives no clue what a 'tuner count vs Jellyfin' comparison actually produces or why an agent would want it.

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 exclusions, and no reference to any alternative among the large set of sibling hdhomerun_check_* tools (e.g. hdhomerun_check_device_reachable, hdhomerun_check_firmware_model). The agent must infer entirely on its own when this check is the right call.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so safety is covered structurally. The description adds real value beyond that: the POST-only transport constraint and the side effect that rerecord=True schedules a future re-recording. It omits whether the underlying file is permanently removed and what permissions are needed, which keeps it short of 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 plus the endpoint line; the alternative-parameter behavior is front-loaded and nothing is padded. The opening line is a raw syntax dump rather than a summary, which slightly hurts front-loading.

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

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

For a destructive two-parameter mutation with no output schema and no schema descriptions, the entry covers both parameters and the transport requirement. It leaves out whether deletion is permanent/irreversible and what the response or failure mode looks like, which matters for a destructive call.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely succeeds: cmd_url is identified as the CmdURL taken from recorded_files.json, and rerecord is explained as a boolean that tells the DVR to record the episode again on a future airing, including the wire form &rerecord=1. No format detail is given for the cmd_url string itself.

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

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

The definition makes clear this deletes a recording from the DVR, expressed as the underlying HTTP command (cmd=delete) against a CmdURL. The verb+resource are specific and the sibling hdhomerun_delete_rule covers rules rather than recordings, so an agent can distinguish them. It loses a point for framing the purpose as raw endpoint syntax rather than a plain statement of what the tool does.

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

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

It states a hard prerequisite — cmd_url must come from recorded_files.json, i.e. hdhomerun_get_recorded_files — and warns that GET is rejected with 400 so the request must be a POST. It does not explicitly contrast with hdhomerun_delete_rule or explain when deletion is preferable to changing/keeping a rule, but the operational context is clear.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known; the description adds no behavioral context beyond that. It says nothing about irreversibility, whether the rule can be restored, or that device authentication may be needed to perform a destructive device operation.

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 dense sentence with the action and both rule families front-loaded; nothing is wasted. The parenthetical combination syntax is compact but readable.

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

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

For a destructive, zero-required-parameter tool with no output schema and 0% documented schema, the description covers identification but not authentication, side effects, or result reporting. Adequate to invoke, not complete enough to invoke confidently.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It does explain the valid identifier combinations (RecordingRuleID alone, SeriesID alone, or SeriesID+DateTimeOnly+ChannelOnly), which is genuinely useful, but leaves device_auth completely unexplained and does not clarify the integer type of date_time_only.

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 (Delete) and resource (Series/Movie rule, DateTimeOnly-ChannelOnly rule), and enumerates the two identification modes. It is clearly distinguishable from the sibling rule tools (add_series_rule, add_datetime_rule, change_rule), 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?

The description implies when the tool applies by listing the rule shapes it handles, but gives no explicit guidance on when to prefer hdhomerun_change_rule or hdhomerun_delete_recording, and no prerequisites (e.g. device_auth requirements) are 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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds the endpoint it hits but does not say whether the change is reversible, what state the device ends up in, or whether auth/lockkey is required for this mutation.

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 sentence with the action front-loaded and the endpoint appended as supporting detail. No filler, though the literal path markup is slightly noisy for an agent-facing description.

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

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

For a zero-parameter toggle with no output schema and annotations covering safety, the description is nearly sufficient. The main omission is a pointer to the inverse operation for re-enabling, which the sibling name largely implies.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The noted endpoint path is extra context rather than parameter guidance.

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 (Disable) and resource (lineup-server connection) with the underlying endpoint path, so the action is unambiguous. The inverse sibling hdhomerun_set_lineup_location is not named, but the paired naming makes the distinction clear enough.

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 name: use it to turn off the lineup location rather than to configure one. There is no explicit statement about when to prefer this over hdhomerun_set_lineup_location or what prerequisites (device reachability, auth) apply.

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 cover the safety profile: read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context by identifying the external cloud endpoint and explaining its fallback role when local broadcast fails, though it does not discuss auth or rate limits.

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

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

The description is front-loaded with the endpoint and then concisely explains the purpose and fallback scenario. Both sentences add useful information without padding.

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

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

The tool is simple, has rich annotations, and has an output schema, so the description need not explain return values in depth. It is nearly complete, with the only minor gap being what happens when device_id is omitted.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does this by mapping device_id to the DeviceID query parameter and showing it as optional via the bracketed URL syntax, though it does not explain behavior when the parameter is omitted.

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 cloud discovery operation and explains that it resolves a device's current LAN IP by DeviceID. It also distinguishes this from local discovery by noting the VLAN scenario where local broadcast cannot reach the device.

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 a clear usage condition: use this when local broadcast cannot reach the device, such as when the client is on a different VLAN. It does not explicitly name the local discovery sibling or state the when-not case, but the context is strong enough for selection.

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 openWorldHint=true and destructiveHint=false, so the network-touching nature is partly covered. The description adds genuine value by disclosing the empty-result possibility and the subnet limitation, but says nothing about how long the broadcast waits or how replies are aggregated; the output schema covers the return shape.

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

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

Front-loaded with the action and protocol, followed by a short caveat and fallback. Four tight sentences; only the doubled-backtick reStructuredText markup is mild noise.

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 need not explain reply contents, and it covers the key operational pitfall. The remaining gap is parameter guidance for the two optional arguments, which is minor for a fire-and-collect discovery call.

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

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

Schema description coverage is 0% and the description never mentions `timeout` or `device_id`, so an agent gets no help understanding the timeout's units or why a device_id would be supplied at all. The protocol detail is useful but does not compensate for the undocumented parameters.

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?

A precise verb-plus-protocol statement: it broadcasts a DISCOVER_REQ on UDP port 65001 and collects DISCOVER_RPY replies. That tells an agent exactly what happens on the wire and implicitly separates it from the cloud and targeted-discovery siblings.

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

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

Explicitly warns that an empty list is a legitimate result and explains why (broadcast does not cross VLAN/subnet boundaries), then names the two alternatives: discover_cloud() or a known IP plus get_discover(). This is exactly the when-it-fails/when-to-use-otherwise guidance an agent needs.

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 non-read-only, open-world, non-destructive behavior, so the safety profile is covered. The description adds the useful VLAN-crossing context for a uni/multicast send, but says nothing about what comes back, whether the call blocks for the timeout duration, or how results are surfaced.

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. It is efficiently written, though its brevity is partly the cause of the gaps elsewhere rather than a sign of good coverage.

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 three undocumented parameters, no output schema, and only terse annotations, the description leaves the agent guessing about timeout semantics, the device_id broadcast default, and the shape of the discovery result. A network-send tool needs more than one sentence.

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 0% and the description only indirectly maps 'known IP' to the required ip parameter. The timeout parameter (units? seconds?) and especially device_id's default of 4294967295 (0xFFFFFFFF) are completely unexplained, which is a real gap given zero schema documentation.

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?

'Send a DISCOVER_REQ directly to a known IP' states a specific protocol action and target, which distinguishes it from the broadcast and cloud discovery siblings by implication. The verb+resource is clear, though it relies on the reader understanding HDHomeRun protocol jargon.

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?

'works across VLANs' gives concrete context for when this is the right choice over hdhomerun_discover_local_broadcast, which is the primary differentiator. It doesn't explicitly name the alternative or state when NOT to use it, keeping it below 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description's added value is the response shape (`<modulation>:<frequency>` or `none`), which helps interpret output in the absence of an output schema, but it says nothing about behavior when the tuner is idle, busy, or out of range.

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 compact sentence with the resource path front-loaded and the return format immediately after. No wasted words, though the endpoint-path notation is cryptic for an agent unaccustomed to that style.

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 read with no output schema, the description does supply the return format, which is the key missing piece. It remains incomplete on the `tuner` parameter and on error/idle-tuner behavior, which an agent needs to call it reliably.

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 0%, so the description must compensate; it only implies via `/tuner<n>/` that the parameter is a tuner index. It never states valid indices, whether numbering starts at 0 or 1, or what happens for an invalid tuner.

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?

Names the resource and endpoint (`/tuner<n>/channel`) and states the returned value is the current `<modulation>:<frequency>` or `none`, so the agent knows this reads the channel a tuner is tuned to. It is distinguishable from `hdhomerun_set_channel` by the read semantics, though the 'get' verb is only implied by the endpoint path rather than stated as a sentence.

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 guidance on when to use this versus alternatives such as `hdhomerun_get_tuner_status`, `hdhomerun_get_channelmap`, or `hdhomerun_set_channel`. The agent must infer 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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds nothing beyond the endpoint path — no note on whether the map is device-wide or per-tuner scoped, no return format, no failure behavior for an invalid tuner.

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?

It is a single short fragment with no filler, which is appropriately front-loaded. But the brevity crosses into under-specification: an endpoint path plus a noun phrase is not a structured description of behavior.

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

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

No output schema exists, so the description should convey what the channel map looks like (entries, channel numbers, frequencies, modulation). It does not, and with the only parameter undocumented, an agent cannot confidently call this beyond guessing the tuner index.

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 single parameter `tuner` has 0% schema description coverage, and the description only surfaces it indirectly via the `/tuner<n>/` path fragment. It does not state whether the index is 0- or 1-based, its valid range, or what happens with an out-of-range value — the description must compensate here and does not.

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 identifies the resource — the configured channel-to-frequency map — and ties it to the `/tuner<n>/channelmap` endpoint, so an agent can infer it is a read of that endpoint. However, it never states a verb explicitly and offers no differentiation from siblings like hdhomerun_get_channel or hdhomerun_set_channelmap; the agent must know the HDHomeRun API to disambiguate.

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 when to prefer hdhomerun_get_channel or hdhomerun_set_channelmap, and no stated prerequisites (e.g., device reachability or valid tuner index). The agent is left to infer usage entirely from the name and endpoint path.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond re-listing return fields, which the output schema already provides.

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?

It is short and free of padding, but front-loads a raw endpoint path and a truncated field list instead of a purpose statement. Brevity here comes at the cost of comprehension rather than from efficiency.

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 and annotations handle returns and safety, so those gaps are acceptable. What is missing is the core question an agent asks first: what this endpoint is for and when to pick it over the other discover 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. Nothing in the text misleads about inputs.

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

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

The description is an HTTP path plus a slash-separated list of field names, not a statement of what the tool does. An agent must infer 'returns device identification/lineup info' from the field names alone, and nothing distinguishes it from hdhomerun_discover_local_broadcast, hdhomerun_discover_local_targeted, or hdhomerun_discover_cloud.

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 and no mention of the four discovery siblings that clearly compete with this tool. The only implicit signal is the endpoint path, which an agent would have to decode on its own.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the default filter value (0x0000-0x1FFF) and the underlying endpoint shape. It does not disclose what a non-default or empty filter looks like, which would have helped.

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 no filler. The trade-off is that brevity here borders on cryptic endpoint notation rather than plain-language explanation, 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?

For a single-parameter read tool with no output schema, the description gives the default and endpoint but does not describe the shape or units of the returned filter value. An agent can probably call it correctly, but understanding the response requires guessing.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'tuner' parameter, and it only partially does via the '/tuner<n>/filter' endpoint notation. It never states the valid range, indexing base, or whether the tuner must currently be active, leaving the required parameter under-specified.

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 identifies the resource as the tuner's current PID filter and gives the default range, which does distinguish it from the sibling hdhomerun_set_filter. But it is written as a raw API endpoint path rather than a clear verb+resource statement, so the read semantics must be inferred from the name 'get' rather than the description 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?

There is no guidance on when to call this versus hdhomerun_set_filter, hdhomerun_get_tuner_status, or hdhomerun_get_tuner_streaminfo. The agent is left to infer that this is the read counterpart to set_filter from naming conventions 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, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description contributes the return-content semantics (a list of get/set item paths), which matters because there is no output schema, but says nothing about output shape (list vs. keyed map) or whether the list is static per firmware.

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 fragment with no filler; the meaningful content (what the call returns) comes immediately after the name echo. Nothing could be removed without losing information.

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

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

For a zero-parameter, non-destructive read with no output schema, stating the returned content is the key missing piece and it is present. Only the precise shape of the returned paths and their intended downstream use are left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The empty schema with additionalProperties=false is self-explanatory.

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 clause after the dash names a concrete resource (the list of get/set item paths the device supports), so the agent knows this is a capability-enumeration call rather than generic help text. It is clear but stops short of explicitly relating itself to hdhomerun_get_item / hdhomerun_set_item.

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 statement, prerequisite, or alternative is given; the reader must infer that this should be called before get_item/set_item to learn valid paths. Nothing is said about when this call is unnecessary or what to do with the result.

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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that the returned value is an IP:port and identifies the underlying /ir/target endpoint, which is useful context, but it says nothing about behavior when no IR target is configured.

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 sentence with the resource named up front and no filler beyond the code-formatted endpoint path. It is terse rather than verbose, though the terse form is also why the purpose needs inference.

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

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

For a zero-parameter read with no output schema, the description is adequate but thin: it states the value is an IP:port but not the shape of a not-configured or error response, and it does not disambiguate against the similarly named hdhomerun_get_target. That leaves real gaps for an agent choosing among ~55 siblings.

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 argument semantics to explain and the baseline of 4 applies. The description correctly implies a no-argument retrieval with no filters or options.

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 fragment names the specific resource — the configured IR-blaster target IP:port — which is more informative than a bare restatement of the title. However, it omits an explicit verb and never distinguishes this from the sibling hdhomerun_get_target or hdhomerun_set_ir_target, so an agent must infer the read-vs-write and ir-vs-plain-target split from the tool 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 when-to-use guidance, no mention of the sibling hdhomerun_set_ir_target for changing the value, and no statement of prerequisites or when this tool is the wrong choice. The agent gets no routing help beyond the tool name.

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, and open-world, so the safety profile is covered. The description adds the meaningful detail that this is a raw CLI passthrough (implying unprocessed output), but it does not say what happens on an unsupported item path or what the raw return looks like.

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 line with no filler, and the identifying CLI form leads. It is efficient but under-specified rather than concise — the brevity comes at the cost of any usable 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?

No output schema and a 0%-coverage parameter mean the description must carry the burden, yet it omits valid item paths, output format, and error behavior. For a generic escape-hatch tool this leaves too much for the agent to guess.

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 0% and the single parameter is named `name` while the description refers to `<item>` and an unlisted `<id>`, leaving the mapping and the accepted item-path vocabulary unexplained. With no enumeration of supported paths, the agent cannot construct a valid call except by trial.

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?

It states a concrete operation (a raw get of any supported item path) and anchors it to the underlying CLI invocation `hdhomerun_config <id> get <item>`. However, "item" is never defined, so an agent cannot tell what class of data this returns or how it differs from the many typed getters like hdhomerun_get_channel or hdhomerun_get_tuner_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?

No guidance on when to pick this generic getter over the dozens of specific siblings (get_sys_model, get_lineup, get_tuner_status, etc.), nor when it is unsafe or inappropriate. An agent must infer that this is a fallback for paths without a dedicated 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint formats and JSON field set, but omits auth requirements, error behavior, and what XML or M3U responses contain.

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 the endpoint and purpose front-loaded, followed by useful JSON field details. The parenthetical provenance is compact and no sentence 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?

For a simple read tool with rich annotations and no output schema, the description covers the endpoint, format choices, and JSON return fields well enough to call it correctly. It leaves some gaps around XML/M3U response content and whether lineup availability depends on location state, but those are minor for this tool's complexity.

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

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

The single fmt parameter has 0% schema description coverage, so the description must compensate. Its .{json,xml,m3u} notation implies the allowed formats and the second sentence adds JSON-specific field meaning, but it does not explicitly map fmt to response behavior or explain differences between JSON, XML, and M3U output.

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 retrieval operation: GET /lineup and explicitly calls it 'the channel list.' It is clearly not a tautology, but it does not explicitly distinguish itself from nearby siblings such as hdhomerun_get_channelmap or hdhomerun_get_lineup_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?

There is no explicit when-to-use guidance, no exclusions, and no named alternatives. An agent must infer from 'channel list' whether this is the right tool versus hdhomerun_get_channelmap, hdhomerun_get_channel, or hdhomerun_get_lineup_status.

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, open-world, so safety is covered. The description adds genuine value by disclosing the two response modes (idle vs scanning) and which fields appear in each, which the annotations cannot convey. It stops short of saying what the agent should do with those states.

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?

Very short and front-loaded with the endpoint, which is good, but the brace-notation state listing is dense jargon that reads like a schema fragment rather than prose. Efficient, yet not maximally scannable.

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 here, and the two-state summary plus field names cover the essentials. Missing is any framing of why an agent would fetch scan status or how it relates to starting/aborting a scan.

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?

Zero parameters, so the baseline is 4; there is nothing parameter-related to document and the description correctly spends no words on it.

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 endpoint (GET /lineup_status.json) and characterizes the payload as 'scan state,' which is a specific enough verb+resource. It does not distinguish this from closely related siblings like hdhomerun_get_lineup, hdhomerun_start_scan, or hdhomerun_abort_scan, so an agent must infer the boundary 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The idle/scanning state enumeration implies a polling use case, but that is inference rather than instruction.

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, so the safety profile is covered. The description's one added piece of behavior is the return semantics ('none' if unlocked), which is genuinely useful since there is no output schema; it says nothing about auth requirements or what a nonzero lock owner string looks like.

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 sentence with the resource path first and the return semantics second. Nothing superfluous and nothing buried.

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

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

For a single-parameter read tool with no output schema, explaining the sentinel value 'none' is the key contribution and it is present. But the sole parameter's meaning is left entirely undocumented, and nothing distinguishes this from the neighboring tuner status 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 coverage is 0% and the single required 'tuner' integer has no description anywhere. The '/tuner<n>/lockkey' path fragment vaguely implies the parameter selects a tuner index, but gives no valid range, indexing base, or whether it is required — the agent must guess.

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?

Names a specific resource (the per-tuner lockkey) and states the return meaning (current lock owner, 'none' if unlocked). The 'lockkey' term is distinctive enough to separate it from the many other hdhomerun_get_* siblings, though it never explicitly says it is the read counterpart of set_lockkey.

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 statement of when to call this versus alternatives, no mentioning of set_lockkey as the mutation counterpart, no preconditions. Usage is only inferable from the name and the word 'current'.

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, idempotentHint, and non-destructive behavior, so the safety profile is fully covered by structured fields. The description adds essentially nothing beyond that – it does not describe what the returned program data looks like, whether a tuner must be locked/active, or what happens when no program is set.

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?

Very short with no wasted prose, but the leading element is an opaque API path in backticks rather than a front-loaded statement of what the tool does; the useful part ('current MPEG program filter') comes second.

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

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

With no output schema, the description should explain what is returned (program number, sub-channel, modulation?) and any preconditions such as tuner lock. It says none of that, and the single required parameter is left undefined, so an agent cannot confidently invoke or interpret it.

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?

There is one required parameter ('tuner') with 0% schema description coverage, and the description never explains what the value means (tuner index, zero- vs one-based, valid range) or how it relates to /tuner<n>/. The path notation 'tuner<n>' is the only hint, which is insufficient compensation for an undocumented parameter.

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

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

The description names the underlying endpoint and identifies the resource as the 'current MPEG program (sub-channel) filter', so an agent can infer it reads a tuner's current program selection. However, it leans on the raw API path rather than a plain statement of the action, and sibling tools like hdhomerun_get_tuner_status or hdhomerun_get_channel are not contrasted.

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 versus hdhomerun_get_tuner_status, hdhomerun_get_channel, or the paired hdhomerun_set_program. The only implied cue is 'current', which hints at a read but is never stated as a usage condition.

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 establish that this is a safe, read-only, idempotent, non-destructive operation. The description adds useful context by naming the endpoint and noting that each recording includes its own `CmdURL`/`PlayURL`, but it does not cover pagination, empty-result behavior, auth requirements, or overall response shape.

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 front-loaded sentence with no filler. Every element, the HTTP method, storage URL, file name, and returned item URLs, contributes directly to understanding the operation.

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

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

For a simple one-parameter read tool with no output schema, the description gives the core behavior and a hint about returned fields. It remains incomplete regarding how an agent should source or format `storage_url` and what the full response looks like beyond each item's playback URLs.

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

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

Schema description coverage is 0%, so the schema only says `storage_url` is a string. The description partially compensates by showing that the parameter is a storage base URL used with `recorded_files.json`, but it does not explain how to obtain the URL, its expected format, or whether it includes a trailing slash.

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 HTTP GET against `recorded_files.json` and explains that the result is a list of recordings available for playback. It is clearly a read/list operation, though it does not explicitly differentiate itself from nearby tools such as `hdhomerun_list_recording_rules` or `hdhomerun_delete_recording`.

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 'available for playback' implies when an agent would use this tool, namely to enumerate playable recordings. However, it gives no explicit when-not guidance or named alternatives for related tasks like listing recording rules or deleting recordings.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that this is a plain HTTP GET to a /discover.json path and enumerates the returned fields, which is useful given openWorld/network behavior. It says nothing about auth requirements, error behavior when the engine is unreachable, or whether it validates reachability first.

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 endpoint and payload fields come first. Given how thin the definition is overall, the terseness is efficient rather than wasteful.

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

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

For a one-parameter read tool with full annotation coverage and no output schema, listing the returned fields is a real plus. Still missing: why one would call this instead of hdhomerun_get_discover, and any auth/network preconditions given the openWorldHint.

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 0% and there is one required parameter, so the description must carry the load. It partially does: embedding '<storage engine BaseURL>/discover.json' signals that the parameter is a base URL to which a path is appended, not a full endpoint URL — meaning beyond the bare name. It omits format details such as scheme/port, trailing-slash handling, or relation to the storage URL field returned.

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 (GET) and resource (/discover.json on the record engine) plus the exact fields returned (FriendlyName/Version/BaseURL/StorageURL/FreeSpace). The phrase 'local record engine' distinguishes it from the device-level hdhomerun_get_discover, though it never names that sibling.

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

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

No when-to-use statement, no prerequisites, and no mention of alternatives such as hdhomerun_get_discover, hdhomerun_poke_record_engine, or hdhomerun_check_discovery_cache_freshness. The agent must infer that this is the record-engine counterpart of device discovery.

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: true`, `idempotentHint: true`, `destructiveHint: false`, `openWorldHint: true`). The description adds that the operation reads the firmware copyright notice, but it does not add behavioral context such as device requirements, caching, or response characteristics.

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 compact sentence with the endpoint and resource front-loaded. There is no redundant or filler text.

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, no-parameter read operation with rich annotations, the description identifies the endpoint and the returned content. The only minor gap is that it does not explicitly state the return type or format, though 'copyright notice' strongly implies a text value.

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?

This tool has zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description does not introduce any misleading parameter expectations.

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 endpoint (`/sys/copyright`) and identifies the resource as the firmware copyright notice. It is clear enough to distinguish this from other sys getters by content, though it does not explicitly name or contrast sibling 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?

Usage is only implied by the purpose: an agent would call this when it needs the copyright notice. The description gives no explicit when-to-use guidance, exclusions, or comparison with adjacent tools like `hdhomerun_get_sys_version` or `hdhomerun_get_sys_model`.

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 and openWorld, so the safety profile is covered. The description adds only the scope word 'device-wide' and says nothing about volume or volatility of the debug output, rate limits, or what the raw dump looks like — minimal added value.

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 clause with the endpoint literal first. Nothing is wasted, though there is little substance to be concise about.

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

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

For a no-param read with no output schema there is no return-value obligation, and annotations cover safety. Still, the description leaves the agent guessing what 'debug info' contains and whether it is a raw passthrough versus structured data, which a short phrase could have fixed.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The empty schema with additionalProperties=false is consistent with the description's no-argument nature.

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?

Names the endpoint ``/sys/debug`` and characterizes the payload as device-wide debug info, which implicitly contrasts with the tuner-scoped sibling hdhomerun_get_tuner_debug. However, the verb is only implied and the phrase is so terse that an agent gets scope but not much else.

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 statement of when to call this versus hdhomerun_get_tuner_debug or the sys model/version/features tools. The 'device-wide' wording hints at a distinction but never tells the agent to prefer or avoid this tool in any situation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the raw API endpoint being proxied and the nature of the payload, but says nothing about response format, size, or device-dependence beyond annotations.

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

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

A single short line with zero waste, front-loading the endpoint and the returned data. The backtick-formatted path is slightly opaque to an agent that does not know the HDHomeRun API, but it is compact and information-dense.

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

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

For a zero-parameter, read-only getter with annotations covering safety, the definition is nearly sufficient, but with no output schema the description should say a bit more about what 'features' contains (e.g., a list of channelmap/modulation identifiers) so an agent knows what it will get back.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to explain and the description correctly does not invent any. Schema coverage is 100% and the empty schema matches the no-argument behavior implied.

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 endpoint (/sys/features) and states what it yields: supported channelmaps/modulations for this device. That distinguishes it from adjacent sys getters like get_sys_model, get_sys_version, and get_sys_copyright. The verb is only implied by the tool name, but the resource and its contents are 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 statement of when to call this rather than get_channelmap, get_sys_model, or the other discovery/sys tools, and no prerequisites or exclusions. Usage is only inferable from the tool name and the endpoint path.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only the underlying endpoint path, with no note on device reachability requirements, auth, or failure behavior for a network-facing call.

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 sentence with the endpoint and the returned value front-loaded; nothing is wasted. It is arguably too terse rather than bloated, which limits it to a 4.

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

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

With no output schema, the description carries the burden of describing the return value, and 'the device model name' covers that at a minimal level. It says nothing about how the value is formatted or what happens if the device is unreachable, leaving gaps for an openWorld network 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?

The tool takes zero parameters, so there is nothing for the description to clarify and no risk of misuse from undocumented inputs; a neutral mid score reflects that it neither helps nor hurts here.

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?

Names the specific resource it returns ('the device model name') and ties it to the /sys/model endpoint, which separates it from siblings like hdhomerun_get_sys_version, get_sys_features, and get_sys_copyright. It stops short of stating an explicit verb, but the 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 call this versus hdhomerun_get_sys_version or hdhomerun_check_firmware_model, both of which an agent might plausibly confuse with a model lookup. The agent must infer usage entirely from the tool name.

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, and open-world, so safety is covered. The description adds no behavioral context beyond the raw endpoint path — nothing about auth/lockkey requirements, whether the device must be reachable, or the shape of the returned string.

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 fragment with zero waste. It is efficient, though its terseness borders on under-specification rather than optimal conciseness.

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

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

For a zero-parameter, no-output-schema read, the description conveys the returned datum (firmware version string) and the endpoint, which is minimally sufficient. It stops short of noting prerequisites such as device reachability or lockkey authentication that other tools in this family reference.

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. Nothing in the schema needs explaining, and the description correctly doesn't waste words on phantom inputs.

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

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

Names the specific resource (firmware version string) and the underlying endpoint /sys/version, which is concrete and unambiguous. It is distinguishable from siblings like hdhomerun_get_sys_model or hdhomerun_get_sys_features by resource, though it never explicitly says so.

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 versus hdhomerun_get_sys_model, hdhomerun_get_sys_features, or hdhomerun_check_firmware_model, which are the obvious near-neighbors. The agent must infer the use case (e.g., version check before firmware compatibility checks) entirely on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds the useful fact that the returned value is a UDP/RTP streaming target rather than an arbitrary string, but says nothing about failure modes when a tuner has no active target or about authentication 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?

One short clause with no filler, so nothing is wasted, but it is under-specified rather than concise — there is essentially only one sentence and no front-loaded usage framing. Compactness here comes at the cost of completeness.

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

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

For a read tool with a required index parameter, no output schema, and 0% parameter coverage, the description should say what the target value looks like (e.g. IP:port or 'none') and how to obtain a valid tuner index. Neither is present, so an agent cannot fully predict the call's result or its parameter domain.

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

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

Schema description coverage is 0%, so the single required 'tuner' parameter is undocumented in the schema; the description only indirectly hints at it via the /tuner<n>/ placeholder. It does not state whether the value is a zero-based index, how to enumerate valid tuners (e.g. via hdhomerun_get_tuner_status), or what happens for an out-of-range value.

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

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

The description identifies the resource (the current UDP/RTP streaming target) and ties it to the /tuner<n>/target endpoint, but the verb is only implied by the tool name. It does not explicitly distinguish itself from the sibling hdhomerun_set_target or hdhomerun_get_ir_target, so an agent must infer which side of the read/write pair this is from the name alone.

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

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

There is no statement of when to call this versus hdhomerun_set_target (its write counterpart) or hdhomerun_get_ir_target, and no prerequisites such as authentication or tuner availability. Usage is only inferable from the name prefix.

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 that this is a read-only, idempotent, non-destructive diagnostic operation. The description adds useful domain context by listing the counter categories (`tun/dev/ts/flt/net`), but does not explain output shape, tuner validity, or device-auth prerequisites.

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?

Extremely compact and front-loaded: one endpoint reference plus the diagnostic categories. No filler or redundant restatement.

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

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

For a simple one-parameter read-only diagnostic tool, the description conveys the endpoint and general counter categories. It remains incomplete on tuner-number semantics and expected diagnostic output, which matters because there is no 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 coverage is 0%, so the description must carry parameter meaning. The `/tuner<n>/debug` path implies the single required `tuner` parameter is the tuner index, which is useful, but it does not specify valid range, indexing base, or error behavior.

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?

Names the exact endpoint `/tuner<n>/debug` and identifies the resource as extended tuner diagnostic counters. That is specific enough to distinguish it from sibling tools like get_tuner_status or get_sys_debug, though it lacks an explicit verb such as “retrieve.”

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

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

Provides no guidance on when to use this instead of get_tuner_status, get_tuner_streaminfo, get_tuner_vstatus, or get_sys_debug. The agent must infer usage from the tool name and endpoint path 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 establish that this is a safe, read-only, idempotent operation. The description adds some behavioral context by showing the raw status fields returned (ch, lock, ss, snq, seq, bps, pps), but it does not explain what those fields mean or whether the raw result should be parsed via another 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?

It is short, but the brevity is under-specification rather than efficient communication. It leads with a technical endpoint path and an unexplained abbreviation list instead of front-loading the tool's 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 read-only tool this is still too sparse: there is no output schema, no parameter explanation, and no explanation of the cryptic return fields. An agent can infer the basic purpose from the name and annotations, but the description does not fully support correct selection or 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?

The schema has 0% description coverage for the single required integer `tuner`, so the description must carry the burden. The `/tuner<n>/status` fragment hints that `tuner` is a path selector, but it does not state valid range, indexing, or meaning.

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 is only an endpoint fragment plus raw status field abbreviations, relying on the tool name/title to convey that it retrieves tuner status. It does not explain what the status represents and gives no differentiation from nearby tools such as get_tuner_vstatus, get_tuner_streaminfo, or parse_tuner_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?

There is no guidance on when to use this tool, when to prefer alternatives, or what prerequisites exist. The many sibling tuner-status/discovery tools make the absence of routing guidance especially costly.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description's one contribution is the return format for detected programs ('<num>: <major>.<minor> [name]'), which is meaningful given there is no output schema, but it omits behavior on an idle tuner or error conditions.

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?

Only one sentence, so there is no bloat, but the most prominent element is a raw endpoint path that an agent cannot act on. A plain purpose clause should have been front-loaded instead of the path.

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

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

With no output schema, the description carries the burden of explaining return values and it only partially does so — one field format is given, with no indication of what else streaminfo reports or how it differs from tuner status. For a diagnostic read tool in a crowded sibling set, this leaves the agent guessing.

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 single required parameter has 0% schema description coverage, so the description must compensate. The '/tuner<n>/' fragment implies that 'tuner' is the tuner index substituted into the path, which is a small but real clarification; valid range, numbering base, and behavior for a nonexistent tuner remain undocumented.

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

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

The description is essentially the API endpoint path plus the name/status string format, not a plain-language statement of what the tool does. 'Detected programs' hints that it returns per-tuner stream details, but there is no verb and nothing to distinguish it from the many sibling read tools (get_tuner_status, get_tuner_vstatus, get_tuner_debug).

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 guidance on when to call this instead of hdhomerun_get_tuner_status, hdhomerun_get_tuner_vstatus, or hdhomerun_parse_tuner_status, all of which occupy adjacent space. No prerequisites (e.g. tuner must be actively tuned) or exclusions are 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral value beyond that: results vary by model/firmware and some devices return "unknown getset variable" — a failure mode an agent would otherwise misinterpret as success.

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 dense, waste-free sentence. It leads with the endpoint path rather than the purpose, which is slightly less front-loaded for an agent scanning for intent, but nothing is extraneous.

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

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

With no output schema, the description is the only source of return-value semantics, and terms like CCI and CGMS are left unexplained. Adequate for a thin diagnostic pass-through given rich annotations, but an agent still won't know the response shape before calling.

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 0% and the single parameter has no description, so the bare schema gives an agent nothing. The description partially compensates by framing it as the `/tuner<n>/` path segment, implying an index, but gives no valid range or how to obtain a valid tuner number.

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?

Names the exact endpoint and states what it returns: virtual-channel auth/CCI/CGMS status. That distinguishes it from the other tuner-scoped reads (get_tuner_status, get_tuner_debug, get_tuner_streaminfo) by content, though it never names those siblings 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 statement of when to call this versus tuning diagnostics like get_tuner_status or get_tuner_debug, and no prerequisites. The caveat that results are model/firmware dependent is useful but describes output variability, not usage conditions.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only the scoping note that results span the household's DeviceAuth(s); it says nothing about whether discovery is required first (openWorld) or how results behave when multiple DeviceAuths exist.

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 tight sentence with no filler and the resource front-loaded. Efficient, though the brevity is partly the problem rather than a virtue given the undocumented parameter.

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?

A read-only list tool whose annotations cover safety, and no output schema exists so return-shape explanation is less critical. Still, an agent cannot tell from this description how the optional device_auth argument changes the result set, which is the one decision it has to make before calling.

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

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

Schema description coverage is 0% for the single optional device_auth parameter, so the description must compensate. It alludes to DeviceAuth scope but never explains the parameter itself: whether omitting it lists rules for all devices, what format the auth string takes, or how results change when it is supplied.

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 (recording rules) with scope qualifier (household's DeviceAuth(s)). Enough to distinguish it from hdhomerun_delete_rule, hdhomerun_add_series_rule, and hdhomerun_change_rule, though it never names those siblings 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 guidance on when to call this versus the other rule-related siblings, and no prerequisites or ordering advice (e.g. list before delete). Only the implied 'read' framing from the name carries any usage signal.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, but the description discloses nothing beyond the input shape: not the return structure, not how malformed lines are handled, not whether errors raise. Listing the expected fields gives some context but leaves behavior opaque.

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 compact sentence with the format up front and no filler. Brevity is appropriate, though the terseness leaves the usage gaps noted above.

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 input format is covered. However, parse-failure behavior and the relationship to the sibling that produces status lines are missing, which matters for correct invocation.

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

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

Schema coverage is 0% and the single parameter `status_line` has no schema description, so the description carries the burden. It does this well by showing the exact key=value format (ch, lock, ss, snq, seq, bps, pps) the string must follow, though it says nothing about field order tolerance, optional fields, or whitespace.

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: parse a tuner status line, and enumerates the expected key=value fields. It does not explicitly distinguish itself from sibling hdhomerun_get_tuner_status, which fetches the raw status, so the distinction is implied rather than 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 use this versus hdhomerun_get_tuner_status or hdhomerun_get_tuner_debug. The agent must infer that this consumes an already-obtained status string rather than retrieving one.

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=true, so the safety profile is covered. The description adds that this is a recompute trigger rather than a data mutation, which is genuinely useful, but says nothing about blocking/synchronous behavior (aside from the '?sync' token in the URL), failure modes, or what a caller gets back.

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 filler, and the effect statement is front-loaded before the usage hint. The raw HTTP path template is a minor piece of noise but also conveys the target parameter.

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?

No output schema exists, so the description should say what a successful poke returns or how failures surface; it does not. Purpose and trigger are complete, but the caller has to guess at the response shape for a fire-and-forget HTTP POST.

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 0%, so the description carries the burden for the single required parameter. The endpoint template '<storage engine BaseURL>/recording_events.post' does identify it as the storage engine base URL, but gives no format example (scheme/host/port) or default.

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 effect: 'Tells the record engine to recompute upcoming record tasks'. This distinguishes it clearly from the read-side sibling hdhomerun_get_record_engine_status and from the rule-mutating 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?

'call after adding/changing/deleting a recording rule' gives an explicit trigger condition tied to sibling operations. It stops short of naming the specific alternatives (e.g. hdhomerun_add_series_rule, hdhomerun_change_rule) or stating when not to call it.

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

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

The description explicitly calls the operation 'Destructive', while the annotations declare `destructiveHint: false`. This is a direct contradiction about the tool's behavioral profile, which is serious for a reboot operation.

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 short and front-loads the endpoint and action. It contains no filler, though the vague warning fragment could be more precise without adding length.

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

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

For a zero-parameter reboot tool, the description identifies the action and endpoint but fails to mention service interruption, authentication requirements, or scope of impact. Worse, its 'Destructive' claim conflicts with the annotations, leaving the agent with an inaccurate behavioral picture.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to document. The schema is empty and the description appropriately does not invent parameter details.

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

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

The description gives a specific verb (reboot) and resource (HDHomeRun), plus the exact endpoint `/sys/restart self`. It is immediately clear what the tool does and no sibling tool performs a restart.

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 only guidance is the vague phrase 'use with care'; there is no explanation of when to use this tool versus alternatives, no prerequisites, and no exclusions. The warning does not tell an agent how to decide whether restarting 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 flag openWorldHint=true, readOnlyHint=false, destructiveHint=false, but the description adds nothing about network/cloud contact, runtime cost, or side effects of the auth-validation flag. For a tool that can reach external services, this leaves important behavior undisclosed.

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 waste, but the brevity comes at the cost of substance rather than delivering efficient 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 needn't be explained, but with four undocumented optional parameters and no statement of which checks run or what enabling the Jellyfin/cloud inputs changes, the description is not sufficient for correct invocation.

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

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

Schema description coverage is 0% for four parameters, and the description explains none of them — not jellyfin_url, jellyfin_api_key, signal_channels, nor validate_device_auth_cloud. An agent must guess that these are optional inputs affecting the checks performed.

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 verb ('Run') and a resource in the sense of a diagnostic suite ('every check'), plus the aggregate report output. However, 'every check' is never enumerated and the numerous hdhomerun_check_* siblings are not referenced, so an agent cannot tell exactly what this covers without reading 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?

No guidance on when to use this versus the granular checks (hdhomerun_check_device_reachable, hdhomerun_check_signal_strength, hdhomerun_check_tuner_count_vs_jellyfin, etc.). There is also no note on whether the optional Jellyfin parameters are required for full coverage.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is partly covered. The description adds the non-obvious behavior that passing 'none' stops the tuner, which is not in the annotations. It says nothing about effect on an active stream, auth/lockkey requirements, or failure behavior for a mutation 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?

One short sentence with no filler, but the leading backticked endpoint fragment is cryptic and the actual verb ('set the tuner's channel') is buried in a code reference rather than 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 3-required-parameter mutation with no output schema and no annotation-level detail about side effects, the description should explain what happens to a currently-streaming tuner, what a successful call returns, and any lockkey requirement. None of that is present.

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

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

Schema description coverage is 0%, so the description must compensate, and it does partially: the endpoint path maps `tuner` to <n>, and the examples 'auto:651000000' / 'auto:60' show the modulation and freq_or_channel formats. However the parameter names themselves are never tied to the examples, and no constraints or valid modulation values are given.

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

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

The description gives the underlying endpoint (`/tuner<n>/channel`) and example values, which implies the tool sets a tuner's channel, but it never states the action in plain prose. It does not distinguish itself from siblings like hdhomerun_get_channel, hdhomerun_stop_tuner, or hdhomerun_set_channelmap.

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 only usage signal is the trailing clause '`none` to stop', which explains one special value rather than when to pick this tool over stop_tuner or get_channel. There is no guidance on prerequisites such as lockkey or an in-progress stream.

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

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

Annotations already flag this as a non-read-only, non-destructive, open-world write. The description adds only example values, not the behavior an agent needs: whether the change persists, whether it disrupts active tuners, or whether device auth/lineup is required.

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?

Extremely tight and front-loaded with the resource and value examples. Nothing is wasted, though the terseness borders on under-specification rather than optimized brevity.

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

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

For a mutation tool with an undocumented 2-parameter schema and no output schema, the description is too thin. It omits what the change affects, whether it persists, and how to select the tuner, leaving meaningful gaps an agent must guess at.

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?

With 0% schema coverage, the description carries the load: it supplies concrete channelmap value examples (us-bcast/us-cable/us-hrc/us-irc) and the tuner<n> notation hints tuner is an index. But it leaves tuner range/selection and validation rules unexplained, so it only partially compensates 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?

The description names the endpoint (/tuner<n>/channelmap 'set') and gives example channelmap values, so an agent can infer it sets a tuner's channelmap. However, the purpose is conveyed through cryptic endpoint notation rather than a plain-language verb+resource statement, and it doesn't distinguish itself from the sibling hdhomerun_set_channel or hdhomerun_get_channelmap.

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 change the channelmap versus when to tune a channel (set_channel) or read the current map (get_channelmap). No prerequisites, persistence behavior, or conditions are 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 disclose that this is a non-read-only, non-destructive, open-world operation, and the description is consistent with that. But it adds no behavioral context about what state changes, whether the tuner must be stopped, whether the filter persists, or what happens to an active stream.

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

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

The single sentence is front-loaded and free of filler, but it is too terse for a mutation tool with two undocumented parameters. Its brevity costs clarity rather than earning concision.

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 mutating tuner-filter operation with no output schema and no parameter descriptions, the definition omits critical call context: the effect of the change, constraints, and expected result. The annotations cover basic safety but not enough for an agent to invoke this confidently.

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 0%, so the description must carry parameter meaning. It usefully shows pid_filter formats such as a hex range or space-separated PID list and implies tuner is the ``<n>`` in the endpoint, but it does not document valid tuner ranges or constraints on the filter string.

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 endpoint and gives example filter values, so it points at setting a tuner filter. However, it never plainly explains what the filter does or how it differs from the sibling get_filter tool, leaving the purpose only partially clear.

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 example syntax for pid_filter but no guidance on when to use this tool, when not to use it, or when to prefer hdhomerun_get_filter instead. Prerequisites such as needing an idle or active tuner are also absent.

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