list_evaluation_runs

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

With no annotations, the description carries the full burden, and it does add behavioral facts: the status enum values (queued/running/finished/error) and the pagination contract ('Page-numbered; page_size is capped at 100'). It leaves auth/read-only and default sort behavior implicit, 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?

Four tight sentences, front-loaded with purpose, then filters, status values, pagination, and routing. Every sentence adds information and none restates the title.

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 paginated list tool with no annotations and no output schema, the description covers the essentials an agent needs: filters, status values, page mechanics, and sibling routing. It omits any indication of returned fields or default sort, a minor gap given no output schema is available.

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. It labels evaluation_id and agent_evaluation_id as 'Filters' and documents both pagination params (page-numbered, page_size cap), covering four of five parameters; only the 'order' parameter's semantics are left unexplained.

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 (list evaluation runs) and immediately distinguishes scope via its filters (evaluation_id, agent_evaluation_id) and the enumerated status values. An agent can tell it apart from get_evaluation_run and list_evaluation_run_results 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?

It explicitly routes the agent to alternatives with the selecting condition: 'Use get_evaluation_run for one run's full detail and list_evaluation_run_results for its per-prompt results.' The filtering and status context further clarifies when this list tool is appropriate.

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