list_scores_v2

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

There are no annotations, so the description carries the full burden. It only says 'List scores', implying a read-only operation, but does not disclose pagination behavior, default sorting, rate limits, or any side effects. The description adds no meaningful behavioral context beyond what 'List' implies.

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 description is appropriately short and front-loaded. The first sentence states the purpose, the second differentiates from fetch_scores, and the remaining lines add essential parameter formatting notes. Every sentence earns its place with no redundancy.

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?

Given the tool has 20 parameters, no annotations, and no parameter descriptions in the schema, the description is severely under-specified. While an output schema exists, the description fails to explain many filter options, pagination semantics, or usage context. It only touches on a few parameters, leaving most behavior unexplained.

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?

The input schema has 20 parameters with no descriptions, and the description clarifies only three: trace_tags, score_ids (comma-separated values) and operator (comparator). This covers only a small fraction of the parameters, leaving the rest without meaningful semantics. The description provides minimal value beyond the raw schema.

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 clearly states the tool 'List scores using the v2 Scores API' and differentiates it from the sibling tool 'fetch_scores' by noting it has 'Richer filters'. This provides a specific verb, resource, and a distinguishing feature, fully meeting the criteria for purpose clarity.

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?

The description explicitly mentions 'Richer filters than fetch_scores', which implies when to use this tool (when needed richer filtering) and identifies an alternative. However, it does not provide explicit exclusion criteria or other alternative tools, so it falls slightly short of a perfect score.

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