iaqualink-mcp

iaqualink_set_pump_speed

Idempotent

Set a Jandy AquaLink variable-speed pump to a named speed from the pump-speed list via WebTouch, confirming first and re-reading speeds to verify the change.

Instructions

Run a Jandy AquaLink RS panel’s variable-speed pump at one of its named speeds (from iaqualink_list_pump_speeds), through WebTouch — the panel makes a pressed speed the running speed at once. Nothing is pressed if that speed already runs; the speeds are re-read afterwards to confirm. Switch back the same way. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "serial": "<serial>",
      "speed": "<speed>"
    },
    "name": "iaqualink_set_pump_speed"
  }
}

Input Schema

Name	Required	Description
`speed`	Yes	A named speed as iaqualink_list_pump_speeds shows it, e.g. "Pool" or "Spa"
`serial`	Yes	System serial number, from iaqualink_list_systems
`confirmToken`	No	ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 11, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the transport (WebTouch), that the panel applies the speed immediately, that nothing is pressed if the speed already runs, and that speeds are re-read afterwards to verify. It also fully explains the confirmation protocol, including the confirmToken fallback and the MCP_CONFIRM_MODE reference, which the annotations do not cover.

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

Conciseness4/5

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

The core action and its preconditions are front-loaded in the first sentences, with the confirmation mechanics deferred to the end where they belong. Some phrasing ('Switch back the same way') is slightly elliptical, and the confirmToken explanation duplicates the schema, but overall it is dense and purposeful rather than padded.

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

Completeness5/5

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

For a mutating equipment-control tool with no output schema, the description covers everything an agent needs: value source, immediate effect, no-op behavior, post-action verification, reversal, and the full confirmation handshake including fallback behavior. No material uncertainty remains about how to invoke it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents serial, speed, and confirmToken in detail (including examples and the 'never on the first call' rule). The description's mention of named speeds and the confirmToken flow largely restates that. Baseline 3 applies since the schema carries the parameter burden.

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

Purpose5/5

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

The description gives a specific verb and resource ('run a Jandy AquaLink RS panel's variable-speed pump at one of its named speeds') and pins the source of valid values to iaqualink_list_pump_speeds, which also implicitly separates it from the rpm-based sibling. An agent can tell what this tool does and what it does not do without opening the schema.

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

Usage Guidelines4/5

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

Usage is well framed: fetch names from iaqualink_list_pump_speeds, then press the speed, and 'switch back the same way' for reversal. The confirmation requirement and its two modes are spelled out. The only gap is that it never states when an agent should prefer iaqualink_set_pump_speed_rpm over this named-speed variant.

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