Reads water status for a confirmed target alias to indicate available water-level data; missing or offline data is reported as unknown. It does not detect cleaning needs or water quality.
Read water status for one confirmed target alias. Missing/offline data is unknown; raw water_level has no documented unit. This does not detect cleaning or water quality.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds meaningful caveats: missing or offline data is treated as unknown, raw water_level has no documented unit, and cleaning/water quality are out of scope. Those details materially help an agent interpret results and avoid overclaiming.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the tool does, followed by caveats and exclusions. Every sentence contributes relevant information with no wasted wording.
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 tool with no output schema, the description supplies the important reliability and scope caveats an agent needs to avoid misinterpreting water status. It could say more about return shape or alias resolution, but the core invocation context is covered.
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 the burden for the single 'target' parameter. It adds that the target should be 'one confirmed target alias', which is useful, but it does not explain alias format, where confirmed aliases come from, or what 'confirmed' means. This is minimally viable rather than complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Read water status') and adds scope boundaries ('does not detect cleaning or water quality'). It is clear what the tool does, though it does not explicitly differentiate itself from sibling status tools such as get_device_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?
It gives a prerequisite ('one confirmed target alias') and a negative scope ('does not detect cleaning or water quality'), which helps an agent avoid using it for those purposes. It does not name alternative tools or explain when to prefer them, so it falls short of full when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.