get_battery_status

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

Goes well beyond the readOnlyHint annotation: it discloses the data source (AirBattery on this Mac), the meaning of each returned field, the 10-minute staleness threshold, that stale levels are last-known rather than current, and that non-Apple/coarse readings should be treated cautiously. This is exactly the interpretative context an agent needs.

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 core purpose, then a scannable field list and an Args section. Most sentences earn their place, though the five-line field enumeration in a narrative description is slightly heavier than strictly necessary.

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 compensates by documenting the return shape and the staleness semantics, and it explains both parameters. An agent can call this tool and correctly narrate its results without any missing pieces.

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 full load and does so: 'device' is described as an optional case-insensitive name filter with example values ('airpods', 'mx master'), and 'include_nearcast' is explained as pulling in devices reported by other Macs on the LAN. Both parameters gain meaning absent from the schema.

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 — 'Get current battery levels of the user's devices' — and immediately names the concrete device classes (AirPods, iPhone, mice, headphones, speakers) plus the data source (AirBattery app). There is no ambiguity about what the tool returns.

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 sibling tools exist, so alternative-routing guidance is moot, but the description supplies clear operational context: non-Apple devices only report while connected, coarse levels tolerate small differences, and near-LAN devices require include_nearcast. It stops short of explicit when-not-to-use guidance.

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