Cache

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.