record_observation

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

No annotations are provided, so the description carries the full burden, and it does disclose important behavioral rules: zero variance is rejected, single point estimates without variance are rejected, and it cites an enforcement policy ('commitment 7'). It does not cover permissions/authorization requirements or reversibility, which are meaningful gaps for a mutation tool with no annotation support, so it is a strong 4 rather than 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 purpose is front-loaded, followed by constraints, a fallback action, and the enforcement note. Each sentence carries information, though phrasing like 'All-zero variance is rejected (n identical outcomes are one effective measurement, not reproducibility)' is somewhat dense. Efficient overall with minimal waste.

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?

Because an output schema exists, return values need not be described, and the description appropriately focuses on preconditions and rejection rules. It also contextualizes the failure case against trial status/executor_output/artifacts. The main missing piece is authorization or permission requirements for this write operation.

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 baseline is 3. The description's note that metrics and variance 'may be sent as JSON-encoded strings' merely repeats what the schema already states in both parameter descriptions. It adds no format, range, or semantics beyond 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 definition opens with a specific verb+resource: 'Record an observation', clarified as 'a data item about a quality'. This is clearly distinguishable from siblings like run_trial and get_trial_status by the fact that it records measurements against a completed trial. It stops short of explicitly contrasting itself with the nearest sibling tools, so it earns a 4 rather than 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?

Usage conditions are explicit and cover both when and when-not: only completed trials may be observed, failed trials' information 'lives in its status, executor_output, and artifacts, not here', and if nothing is concludable the agent is routed to close_programme 'abandoned'. This is precisely the when/when-not/alternative structure that scores top marks.

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