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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description reinforces rather than contradicts that by stating budgets and pauses come back as proposals and "nothing is ever changed." It adds genuinely non-obvious behavior: an immediate guardrail-breach flag, an honest verdict only after the window, and a scheduler prompt only created with owner consent. It doesn't describe what happens on a rejected or malformed reading, which keeps it from 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 two-mode framing ("Without a reading: … With a reading: …") is a good structural device and is front-loaded. However, the sentences are long and overloaded with semicolons, packing guardrails, verdicts, close payloads, and scheduler consent into two paragraphs. Tightening would improve call-time readability without losing content.

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 high-complexity tool with nested objects and 5 parameters, the description covers both invocation modes, the safety posture, and the downstream handoff; an output schema exists so return values need not be explained. The one substantive gap is that the three required structural inputs (engagement, engagement_sha256, experiments) and the schedule object are never explained, leaving the agent reliant on field-level schema docs at 40% coverage.

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 only 40%, so the description should carry more weight, and it never names engagement, engagement_sha256, experiments, or schedule explicitly. It does add conceptual meaning for the reading payload by saying it is compared against the registered baseline, minimum volume, and guardrails, which tells the agent which fields matter. The nested reading fields (min_effect, source, spend) and the schedule options remain undocumented outside 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 description states a specific verb+resource pairing (read back a running experiment) and splits the behavior into two recognizable modes: with and without a reading. It names the sibling record_outcome_experiment as the consumer of the close payload, so an agent can place it in the workflow. It falls short of 5 because the opening clause is a dense run-on ("the read-back schedule for every open experiment and a routine prompt for a host scheduler…") that makes the core action harder to extract than it should be.

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 branching guidance: call without a reading to obtain the schedule, call with a reading to compare against baseline and guardrails. It also names the handoff to record_outcome_experiment after the window closes. It does not rule out alternatives among the many siblings (get_resource, fetch, record_outcome_decision), so the agent must infer that this is the only tool for live experiment check-ins.

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