get_inverter_status

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the call returns live (real-time) data rather than cached/config values, and omitting the id fans out across every configured inverter. No rate-limit or error behavior is mentioned, keeping it out of the top band.

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 plus a short Args block, with the resource and returned fields front-loaded. Efficient and scannable; the Args block slightly duplicates schema structure but earns its place by supplying the omitted-id semantics.

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 detailed, and the read-only annotations cover the mutation question. With a single optional parameter whose meaning is explained, the definition supplies everything required to invoke it correctly; only sibling routing is missing.

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 burden, and it does compensate: inverter_id is identified as a Modbus device id and the null/default case is explained as 'read every configured inverter.' That meaningfully exceeds the bare integer/anyOf schema, though it doesn't give format or valid-range 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 names a specific resource (hybrid inverter status) and enumerates the data returned (power, battery, temperatures, AC voltages/currents, PV strings). It distinguishes itself from siblings somewhat by emphasizing 'live data,' which separates it from get_inverter_info, but it never names that sibling explicitly, so the boundary must be inferred.

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 parameter-level note that omitting inverter_id reads every configured inverter. There is no statement of when to prefer this tool over get_inverter_info, get_plant_status, or get_battery_status, so the agent must infer routing from the 'live data' framing alone.

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