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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results carry units and that this is a prerequisite step, but says nothing about ordering, size, or failure modes when no CTs are configured.

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, zero filler, and the what-it-returns statement is front-loaded ahead of the call-ordering advice. Every sentence earns its place.

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 carries the return-value burden and does name the returned content (inputs, outputs, units). It could note the likely key/name field an agent needs to feed into 'query', but for a simple discovery call it is sufficient.

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?

The tool takes zero parameters, so there is no argument semantics to explain and no schema text needed. Baseline for a parameterless tool is 4.

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?

'List' plus a precise resource ('IoTaWatt inputs (physical CTs/VTs) and calculated outputs with their units') tells the agent exactly what comes back. It implicitly separates itself from 'query' by being the channel-enumeration step, though it never names a sibling explicitly.

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?

'Always call this first ... before querying' gives clear sequencing and the condition that selects this tool over the query/energy tools. It stops short of stating exclusions versus get_config, which could plausibly overlap in exposing configuration.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description usefully adds the unit (Wh) and that output channels default to all discovered outputs, but says nothing about return shape, pagination, or data freshness.

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 tight sentences, front-loaded with the resource and its unit, with the usage hint placed after. No filler, though the trailing 'etc.' is slightly loose.

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 4-parameter, zero-required read-only tool with no output schema, the description covers intent and units but omits the meaning of the 'end' default ('s') and any indication of return format or time-range limits. Adequate but with clear gaps.

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 75%, so the schema already documents begin, group, and channels. The description reinforces interval grouping and channel selection but adds no syntax or default behavior beyond the schema, and the undocumented 'end' parameter (default 's') is left unaddressed. Baseline 3 fits.

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 gives a specific verb+resource ('Energy consumption (Wh) broken down by interval') and names the scoping option (all or selected output channels), so an agent knows exactly what it retrieves. It does not explicitly contrast itself with siblings like query or snapshot, which keeps it from a 5.

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?

'Use for today's hourly breakdown, daily totals, etc.' provides concrete usage examples that imply when the tool fits. However, it gives no exclusions and never names an alternative (e.g., query or sample_waveform) for cases where interval energy isn't the right call.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the data comes from /config.txt, which tells the agent this is a local static-file read rather than a live device probe. It says nothing about freshness, whether the config is cached, or error behavior when the file is missing.

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?

A single dense sentence that front-loads the verb and resource before listing the returned contents. Every clause earns its place by describing the payload. It is slightly list-heavy, but nothing is wasted.

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 usefully compensates by enumerating what the configuration contains (input channels, CT models, calibration factors, output scripts). With zero parameters and read-only annotations, there is little else an agent needs before calling it; only the missing sibling-routing guidance keeps it from a 5.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description cannot add parameter meaning because there is nothing to parameterize, and it correctly avoids inventing any.

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 (Get) and resource (full IoTaWatt device configuration), then enumerates the concrete payload: input channel definitions with names, CT models and calibration factors, plus output scripts. That is far more than a restatement of the name. It stops short of naming which sibling to use instead (e.g. discover or status), so it is clear but not explicitly differentiated.

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 description never says when to reach for this tool versus status, discover, snapshot or query. There is no mention of prerequisites or exclusions, so the agent must infer usage from the resource name alone. The source path (/config.txt) hints at a static-config read, but that is inference, not guidance.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the device stops sampling while it answers, and results are one row per line. This is exactly the kind of side-effect disclosure annotations cannot convey.

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, purpose front-loaded, then prerequisite, then output shape and performance caveat. Every sentence carries information; nothing is padded.

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?

There is no output schema, and the description partially compensates by noting the one-row-per-line result shape and the sampling stall. Combined with a high-coverage input schema, an agent has enough to call this correctly, though return fields beyond row structure are unspecified.

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 86%, so the schema already documents begin/end/group/limit/select/format/missing in detail, including units, ranges and defaults. The description adds no parameter-level information, so the baseline 3 applies.

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 ("time-series query against the on-device log") and names the device, which is unambiguous. It does not, however, differentiate itself from the sibling energy_by_interval, which is also a time-series retrieval tool, so the agent must infer the boundary.

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?

Gives a clear prerequisite ("Use discover first to know valid channel names") and practical guidance ("prefer a few well-scoped queries"). No explicit when-not condition or direct comparison to alternative retrieval siblings, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, non-destructive), but the description adds substantial context beyond them: values are raw ADC counts not engineering units, there is no CT/VT phase correction so angles are approximate, and it requires the admin user on a password-protected device. The auth requirement and data caveats are exactly the behavioral disclosures annotations cannot carry.

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?

The core action and scope are front-loaded in the first sentence, with interpretation and caveats following. It runs to several sentences, and the load-interpretation examples are somewhat illustrative padding, but each sentence still contributes practical context for reading the output.

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?

There is no output schema, so the description carries the burden of describing the return, and it does list the returned shape metrics (crest factor, harmonics, distortion, phase lag) plus the optional raw sample pairs. It stops short of stating framing, ordering, or an example envelope, but it is largely sufficient for correct invocation and interpretation.

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 100%, so both parameters are already documented in the schema. The description reinforces the 'single CT input' notion and the pair count (~640) that maps loosely to include_samples, but adds little syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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: 'Capture one AC cycle of raw voltage and current samples... from a single CT input' and enumerates the derived metrics. It sharply distinguishes this from siblings like snapshot by clarifying it is 'a snapshot of everything on that CT, not of one appliance.' An agent can identify what it does 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.

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

The description explains what the readings reveal (heater vs motor vs electronics) and tacitly implies when it is useful, but it never explicitly names when to use it versus siblings (snapshot, query, watch). Usage is inferable rather than stated, and no alternatives or exclusions are given.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds useful temporal context (a 5-minute averaging window, default to all discovered outputs) beyond the annotations, but says nothing about refresh cadence, staleness guarantees, or failure behavior.

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 terse sentences that front-load the core semantic (what value is returned) before the optional filtering behavior. No filler wording; slightly clipped grammar but nothing wasteful.

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 single-optional-parameter read tool with annotations covering safety and no output schema required, the description supplies what an agent needs: the value definition, the time window, and the default scope. Only unit/return-format detail is absent, which is acceptable given the schema coverage.

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 100%, so the 'channels' parameter and its omission default are already documented. The description restates the default behavior and adds the nuance that outputs are 'discovered', which is marginal added value on top of 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?

The description states a concrete resource and semantics ('latest instantaneous power, a single averaged value over the last 5 minutes'), which clarifies the otherwise opaque tool name 'snapshot'. It does not, however, explicitly distinguish itself from siblings like energy_by_interval, query, or watch, so an agent must infer the routing.

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?

Usage is implied ('latest instantaneous power') and the optional channel restriction is described, but there is no explicit when-to-use guidance or exclusion relative to query, energy_by_interval, or sample_waveform. The agent must infer that this is the lightweight current-reading tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantive behavioral context by listing exactly what status information is returned (firmware version, uptime, WiFi SSID/RSSI/IP, heap memory, AC frequency, data log ranges), which is valuable because there is no output schema.

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?

The description is a single, front-loaded sentence with no filler. Every phrase names a concrete piece of status information, so no words are wasted.

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 parameterless read-only status tool with no output schema, the description provides the necessary return-value detail by listing the status fields. Annotations cover the safety profile, and no parameter or return explanation 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?

The tool has zero parameters, so the baseline of 4 applies per the scoring rules. The description does not need to explain parameter semantics, and it correctly avoids irrelevant parameter discussion.

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 identifies a specific resource (IoTaWatt device status) and enumerates the exact fields returned (firmware, uptime, WiFi, heap, AC frequency, log ranges), making the purpose clear. However, it uses a noun phrase without an explicit verb and does not differentiate itself from siblings like get_config or snapshot.

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 explicit guidance on when to use this tool versus alternatives such as get_config, snapshot, or query. The usage is implied by the name and field list (check device health/status), but no conditions or exclusions are stated.

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

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

Annotations only declare read-only/non-destructive safety; the description adds substantial non-obvious behavior: poll rate (once per second), output shape (one CSV row per second with watts/volts), and critically that 'the call takes as long as the duration asked for' — a blocking-duration characteristic an agent must know before invoking. This is genuine value beyond annotations.

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?

Four sentences, front-loaded with the core capability and resolution, then output, then use case, then the duration caveat. Efficient with little waste, though the output and use-case sentences could be tightened.

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 3-param, no-output-schema read tool, the description covers resolution, output format, blocking duration, and intent. It omits error/limit handling and interaction with the 'channels' default, but is largely complete for correct invocation.

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 100%, so the schema already documents pf, seconds, and channels thoroughly. The description nonetheless reinforces the time semantics ('given number of seconds', 1s resolution) and the watts-vs-volts per input type, adding light value without redundancy.

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 (live view/polling) and resource (device inputs over a duration), and crisply differentiates from the stored-log sibling 'query' by noting it is 'finer than the stored log' at 1-second resolution. An agent can distinguish it from snapshot or energy_by_interval without opening a schema.

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?

Gives a clear use case ('catch an appliance being switched on or off right now') that tells the agent when this tool is appropriate. It does not explicitly name when to avoid it or which sibling to prefer for historical data, so it stops short of the top band.

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