get_experiment_results

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

With no annotations at all, the description carries the full burden and does so: results are partial while ``status`` is REPLAYING or SCORING, ``aggregates`` is empty until scoring runs end, ``errored`` counts mean the Evaluator's own code broke, ``unknown`` means no judgement, and comparability failures must be reported as no-change. It also discloses the object-store side effect (auto-stored output, preview with an ``@obj_123`` id), which is behavior an agent must know before calling.

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 first sentence is front-loaded with the core purpose and the dense middle is largely necessary return-value documentation given there is no output schema. Some density could be trimmed (the ``pipeline_metrics`` aside, the repeated 'each side's' phrasing) and the trailing object-store boilerplate does not earn much space, but overall the content justifies its length.

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 and only 0% parameter coverage, the description compensates by documenting the return structure field by field: ``metrics``, ``delta``/``delta_pct``, ``change``, ``paired_test_cases``, ``pipeline_metrics``, per-test-case Session breakdowns, ``headline``/``normalized_means``, ``comparable`` and ``aggregates``. An agent can both call the tool and interpret its output without further documentation.

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 0%, so the description must compensate. ``max_test_cases`` is explained with a crucial semantic detail — '``metrics`` still cover every test case' — which prevents the agent from assuming metrics are truncated too. ``experiment_id`` is only restated ('The Experiment's id'), but that parameter is self-evident, so the gap is minor.

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 opening sentence gives a specific verb and resource plus the shape of the payload: 'Reads an Experiment's results: each Metric, candidate against baseline, then each test case.' It is clearly a results-retrieval tool, distinguishable from metadata tools like get_experiment or run-management tools like list_experiment_runs.

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 routes the agent explicitly: find the experiment with ``list_experiments`` and resolve evaluator ids with ``list_evaluators``. It also gives conditional usage rules ('Say a Metric improved or regressed only from ``change``', 'When ``comparable`` is false ... report no change'). It stops short of naming sibling result tools such as get_experiment_run or get_evaluation_run as alternatives, so it is strong but not fully disambiguating.

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