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

Beyond the annotations, the description discloses that the call waits up to 3 seconds, returns a final status when available, and explains the duplicate/stale/conflict semantics of command_id. It also clarifies that executed/failed means 'a report, not physical proof' and that retry protection is not durable, which is valuable context for a destructive, non-idempotent command tool.

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 long but front-loads the core action, then proceeds through command_id semantics and status meanings in a logical order. Every paragraph adds distinct operational value for safely invoking a destructive command tool.

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 complex command-execution tool with no output schema, the description covers behavioral semantics and status outcomes very well. It is slightly incomplete on output shape and on the non-command_id parameter formats, but its rich retry and status guidance makes it largely 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?

Schema coverage is 0%, so the description must carry parameter meaning. It thoroughly explains command_id (optional, duplicate behavior, stale/conflict cases) but only minimally addresses device_id, capability, and arguments, leaving those required parameters without format or selection guidance.

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: 'Ask a gadget to run one command capability with JSON arguments.' It also distinguishes this tool from the sibling gadgets_command_status by explicitly telling the agent to poll that tool when the command is still pending.

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 explicit when-to-use and when-not-to-use guidance: poll gadgets_command_status instead of resending a command, omit command_id for new actions, never reuse an ID for a new action, and inspect state before retrying after uncertain outcomes. The status-specific guidance for not_delivered, timed_out, and unconfirmed further clarifies safe next steps.

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 safety is covered. The description adds valuable domain behavior beyond that: executed/failed are device reports rather than physical proof, not_delivered can be safely retried, and timed_out/unconfirmed require a state check before further action.

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 front-loaded with the core action and then compactly explains how to interpret the resulting statuses. Every clause earns its place and 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 read-only receipt tool with no output schema, the description covers the key status interpretations and the safety of follow-up actions. It stops short of explaining where command_id comes from or explicitly routing to a state-check sibling, but it is otherwise complete enough for correct use.

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?

There is one required parameter, command_id, and schema description coverage is 0%, so the description must compensate. 'Read a command receipt' implies the ID identifies a receipt, but it gives no format, source, or uniqueness details. This is minimally viable for a single obvious identifier but leaves a clear gap.

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 phrase 'Read a command receipt' states a specific verb and resource, and the status handling makes clear it is about retrieving command outcome rather than sending or inspecting device state. It does not explicitly name a sibling alternative, but the focus on receipt distinguishes it from gadgets_command and gadgets_get_state.

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 gives clear conditional guidance: not_delivered is safe to resend as a new action, while timed_out/unconfirmed need a state check before acting again. It does not name the state-check tool directly, but the when-to-act guidance is concrete and actionable.

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, covering the safety profile. The description adds meaningful value by disclosing that output is redacted ('without tokens, state, arguments or raw errors'), which tells the agent the report is sanitized. However, it says nothing about report size, format, or what it does contain.

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, front-loaded sentence with no filler. The trailing redaction clause is terse to the point of being slightly cryptic, but it earns its place by signaling sanitized 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?

With no parameters and no output schema, the description carries the burden of explaining what the report contains, yet it only describes what is excluded, not what an agent will actually get back. Annotations cover safety, but the return-value gap leaves the definition only minimally viable.

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 and schema coverage is 100%, so there is nothing for the description to clarify. Baseline 4 applies for a no-parameter tool.

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 the verb ('Get') and the object ('an allowlisted support report'), but 'support report' is vague about what diagnostic content is actually returned. It does not differentiate from siblings like gadgets_get_state or gadgets_read_events, so an agent cannot tell why it would pick this over reading state directly.

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 guidance on when to use this tool versus the sibling diagnostics-adjacent tools (get_state, read_events). The description implies a diagnostic/support purpose but gives no trigger condition or exclusion.

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 real value beyond that by defining what 'state' means ('the device's own report; it does not prove a physical effect') and naming the freshness values, but says nothing about error behavior or what an offline device returns.

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, each carrying distinct information: the operation, the semantic caveat about reported state, and the identifier flexibility. Front-loaded and free of filler.

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 does the work of explaining the return: state plus a fresh/stale/offline freshness classification, along with an important trust caveat. Only minor gaps remain (behavior when the device is offline, failure modes).

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% – the single parameter is documented only as a string titled 'Device Id'. The description compensates by stating that device_id accepts either the gadget's ID or the user-assigned name, which is exactly the ambiguity the schema leaves open.

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 ('Read') and resource ('a gadget's last reported state and freshness'), with the freshness values enumerated. It distinguishes itself implicitly from gadgets_read_events and gadgets_command_status, but never names a sibling to sharpen 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?

No explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. Usage is only implied: 'last reported state' signals a current-status lookup rather than an event history or command path, so an agent can infer the intent but gets no routing help.

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=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description adds real value beyond them: a prompt-injection warning that maker-authored descriptions are information about the device, not instructions. It also indicates the listing exposes freshness and simulated labels, hinting at data staleness. It does not describe pagination or ordering, but that is not required for a parameterless list.

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 sentences, front-loaded with the identity and contents of the resource, then the usage directive, then the safety caveat. Every sentence earns its place, though the parenthetical "(what each one does)" is mildly redundant against "capability_descriptions".

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 burden of explaining return values, and it does so by enumerating the exposed fields (capabilities with argument contracts, event names, availability, freshness, simulated labels). Combined with the read-only annotations and entry-point guidance, an agent has enough to call it correctly; only the shape/format of the returned structure is left 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?

The schema declares zero parameters, so per the rubric the baseline is 4 and there are no parameter semantics left to clarify. The description appropriately spends no effort on arguments and instead documents the content of the result set.

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 ("List gadgets") and defines the unfamiliar term by enumerating what the listing contains: callable command capabilities with argument contracts, capability descriptions, event names, availability, freshness and simulated labels. This makes clear what the tool returns. Sibling differentiation is only implicit via "Call this first" rather than naming when to prefer gadgets_get_state or gadgets_read_events, so it stops short of 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?

"Call this first" is an explicit ordering instruction that positions this as the discovery entry point for the gadget family, which is genuinely useful guidance. It does not, however, state when-not to use it or name any alternative sibling tools and the conditions that select them.

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 (readOnly, non-destructive, closed-world), and the description adds real behavioral detail beyond them: pagination via cursor, in-order delivery, and the recovery protocol for history_lost/cursor_reset error states. Only the shape of returned events and the meaning of an exhausted stream remain unstated.

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 tight sentences, front-loaded with the core action, then the pagination contract, then the error-recovery rule. Every sentence carries instruction the agent needs and none is padding.

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?

No output schema exists, so the description should ideally say what an event looks like or that the response carries next_cursor and the empty/end-of-stream signal. It covers the read loop but leaves result shape, limit semantics, and device filtering unspecified, so it is only adequately complete for a 3-parameter paginated reader.

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% and none of the three parameters carry descriptions, so the description must compensate. It explains the cursor lifecycle well (null to start, next_cursor thereafter) but leaves 'limit' (default 32) and especially 'device_id' filtering completely unexplained; it also names the value 'next_cursor' where the schema names it 'cursor'.

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?

Specific verb+resource ('Read buffered device events') with a concrete example (button presses) and an ordering guarantee ('in order'). It reads distinctly from siblings like gadgets_get_state or gadgets_list_devices, though it never explicitly contrasts itself with them.

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 procedural invocation guidance (start with null cursor, then pass next_cursor, re-read with null cursor on history_lost/cursor_reset), which is genuinely useful. It does not, however, say when to prefer this over gadgets_get_state or the other siblings, so usage selection is left implicit.

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