Compare Experiment Runs

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial extra context: the required history.read grant, the fact it does not execute, retrain, expose or mutate records, and the shape of the output (recorded changes, unknown evidence, finite numeric deltas, no causal claims). That is exactly the added-value disclosure expected when annotations cover the safety profile.

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?

Three sentences, front-loaded with the core compare action and followed by constraint/return/routing details. Every clause carries information, though the 'never causal conclusions' idea is echoed again in the run_b schema description, making it slightly repetitive rather than maximally tight.

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?

With an output schema present, return-value detail need not be in the description, and the remaining gaps an agent needs are covered: the permission requirement, the no-side-effect guarantee, the directional semantics, and the pointer to apizr_experiment_show for underlying evidence. Nothing required to call it correctly is missing.

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 run_a and run_b are already fully documented, including the directional A-to-B semantics the description also mentions. The description adds no syntax, prefix-uniqueness rule, or format guidance beyond what the schema states, so the baseline 3 applies.

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?

States a specific verb and resource ('Compare two verified local Runs') with explicit scope ('directionally from A to B using canonical experiment comparison'), and distinguishes itself from the sibling by redirecting to 'inspect show for the original evidence behind differences.' An agent can tell it apart from apizr_experiment_show/list without opening any schema.

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?

Gives clear context (comparing two existing runs) and states the precondition ('Requires the configured project's history.read grant'), plus points to apizr_experiment_show for raw evidence. It does not explicitly frame when-not to use it beyond 'never causal conclusions,' so it falls just 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.