get_experiment

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

No annotations are supplied, so the description carried the full burden and does disclose a lot: the status lifecycle (REPLAYING, SCORING, then ENDED/FAILED), per-side fields run_counts, scoring_counts, error and experiment_run_id, retry semantics for failed replays/scorings, and the cost signal 'Free to call.' That is strong behavioral context, but it stops short of stating permission/auth requirements. A 3 reflects solid disclosure with that one notable gap.

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 core prose is dense and front-loaded, with the state-machine and per-side field explanation earning its place. The trailing block about automatic object storage, formatted previews, @obj_123 IDs and object-store tools is generic boilerplate repeated across tools, and the ':param'/':returns:' Sphinx fragments mixed with prose read awkwardly.

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 no output schema, the description does the work of describing return contents field-by-field and notes what is deliberately omitted (scored Sessions), which is exactly what an agent needs. The only shortfall is the absence of any permission or access-level statement for a read 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?

One parameter at 0% schema coverage, so the description must compensate and it partly does: ':param experiment_id: The Experiment's id, from list_experiments' adds provenance the schema lacks. It does not add format details (ID shape, whether an object ID is accepted), leaving the agent with a pointer but no syntax guidance.

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?

Opens with a specific verb and resource: 'Reads one Experiment: its test cases and how far each side has got.' It immediately scopes what is and isn't returned, letting an agent distinguish it from get_experiment_results and get_experiment_run without opening schemas.

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?

Explicitly states when to call it ('follow an Experiment after create_experiment, update_experiment or a rerun, and to see why a side failed') and routes to alternatives by name: get_experiment_results for per-test-case Sessions, rerun_failed_experiment for retries, get_session_replay for diagnosing a failed replay. Exclusions are stated, not inferred.

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