ipa_laser_power

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

With no annotations, the description carries the full burden and does well: it discloses the returned fields (dated measurements plus deltas since first and previous), the empty-state behaviour (explicitly reports nothing measured, then gives the protocol and a contact), and the analytical caveat that cross-light-path comparison is invalid. It does not mention permissions or response size, which keeps it short of a 5.

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 content — what is returned and how deltas are computed — is front-loaded, and every later sentence adds usable information (the scope id source, the empty case, the light-path caveat). Slightly loose phrasing ('says so and gives the protocol and whom to ask') costs a little, but there is no 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?

For a three-parameter read tool with no output schema and no annotations, the description is unusually complete: it covers output contents, delta semantics, empty results, and the id source for scope. The remaining gap is the unaddressed optionality of all parameters, which matters given a null default on scope.

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 must compensate: it explains that 'scope' is an id from ipa_find, and implicitly covers line_nm and path via 'laser line' and 'light path'. However, it never maps these terms explicitly to the parameter names, never states units or format for line_nm, and says nothing about the fact that all three parameters are optional and default to null.

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 the specific quantity (laser power at the sample), the breakdown dimensions (scope, laser line, light path), and the shape of the result (every measurement by date with per-cent deltas). It is clearly a measurements-retrieval tool and does not overlap with siblings like ipa_psf or ipa_status, though it never states an explicit verb such as 'return' or 'list'.

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 supplies one concrete prerequisite — the scope must be an id obtained from ipa_find — and warns that comparisons are only valid within a single light path, which is real usage context. It gives no guidance on the case where scope is omitted (all three parameters are optional with null defaults), nor states when the tool should be preferred over other measurement endpoints.

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