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

Beyond the annotations, the description discloses validation rules that materially change how results must be interpreted ("Low volume forces INCONCLUSIVE; a broken guardrail is never a WIN") and enumerates outputs: an experiments.jsonl line, a learning candidate, and an anonymised report the owner may choose to share, implying no automatic disclosure. The one gap is that "Returns a line for experiments.jsonl" plus "Register/close" reads like state mutation while readOnlyHint=true, so the agent is left to infer that nothing is persisted server-side.

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, front-loaded with the two actions, then the invariant rules, then the returns—a sensible ordering with no filler. The parenthetical field enumerations partly duplicate schema content and add density, keeping it from a 5.

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 nested oneOf tool with an output schema, the description covers the decision-relevant essentials: both modes, the two outcome rules, and the shape of what comes back. The remaining ambiguity is whether the experiments.jsonl line is written or merely returned, which matters given readOnlyHint=true and would be worth one clarifying clause.

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% and the schema itself documents engagement, engagement_sha256 (hash-mismatch meaning) and the register/close oneOf branch. The description's field lists restate what the schema already requires per action rather than adding format, ordering, or precedence rules (e.g. what direction or target default to). Baseline 3 is appropriate when structured fields carry the semantics.

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 verb and resource and splits the tool into two named modes ("action register" with change, metric, baseline, window, min volume, guardrails; "action close" with observed, volume, guardrail results, verdict), so an agent knows exactly what can be recorded. It does not name or distinguish the close-relative siblings such as read_back_outcome_experiment or record_outcome_decision, so 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?

"Register a test before it goes live ... then close it" gives explicit lifecycle sequencing: register first, close when observations exist, with the action const in the schema binding each mode. There is no statement of when-not to use this tool or which sibling to choose for adjacent tasks (e.g. recording a decision), so it falls short of full alternative routing.

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