get_device_info

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile and repeatability are covered by structured data. The description contributes the notable behavioral detail that the returned configuration is the 'present' one, implying a live snapshot rather than cached data. It does not state whether the call actually touches the instrument bus or whether it can fail/time out on a disconnected device.

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 compact clause with zero filler, front-loading the most identifying fields (model, serial, firmware). It is a noun phrase rather than a sentence, which makes it slightly less self-explanatory as a standalone statement but costs no reading effort.

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?

Given zero parameters, a full output schema, and annotations covering safety and idempotency, the definition only needs to establish purpose – which the field list does adequately. The only missing element is a usage cue relative to the measurement siblings, a minor gap for such a simple read-only query.

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 nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the tool is argument-free by framing itself purely as a retrieval of device attributes.

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 enumerates exactly what is retrieved: instrument model, serial number, firmware, VISA resource, and current measurement configuration. Combined with the verb in the name (get_device_info), the resource and scope are unambiguous, and the other siblings (read, measure, sample, burst) are clearly measurement operations rather than identity queries. It stops short of an explicit sentence stating the action, relying on the name for the verb.

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 call this versus the measurement siblings, and no stated preconditions (e.g., whether a VISA session must already be open). An agent must infer that this is a discovery/identity call made before measurement, which is plausible but not stated anywhere.

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