Show Experiment Evidence

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, and the description still adds real context beyond them: the required history.read grant, that producer/capture evidence is included only when retained, that unknown provenance is surfaced as unknown, and an explicit list of non-actions (no code execution, no provider load, no capability exposure, no mutation).

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?

Four tight sentences, front-loaded with the core read action before evidence, auth, and negative-scope clauses. Dense but every clause is load-bearing; only the trailing diff pointer feels slightly bolted on.

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 single-parameter read tool with an output schema, full annotation coverage, and 100% schema description coverage, the description supplies the missing pieces an agent needs: auth requirement, evidence/provenance semantics, and explicit non-effects.

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 100% and the run_id description already documents the digest/prefix format and ambiguity refusal, so the description's 'exact digest or unique prefix' adds little new meaning. Baseline 3 applies when the schema carries the parameter burden.

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 ('Read one verified recorded Run and its intended Plan') plus the lookup key (exact digest or unique prefix). This clearly separates it from siblings like apizr_experiment_list (enumerate) and apizr_experiment_diff (compare two identities).

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?

Names the sibling alternative and its trigger condition ('compare two identities with diff'), which routes the agent away from this tool for comparison work. It stops short of stating when-not-to-use for the other siblings (list, analyze, readiness).

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