list model versions

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, non-destructive). The description adds substantial behavioral context beyond that: the owner/admin authorization requirement with 403, the 200-record cap with no pagination, newest-first ordering, that the endpoint is deliberately NOT feature-flag gated, and the comparable_to_parent discontinuity warning for interpreting deltas. No contradiction with annotations.

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?

Dense but every sentence earns its place: purpose, use case, HTTP verb and API-key scope, complete return shape with field types and null semantics, ordering, cap, and three edge-case notes (feature-flag gating, auth, pagination). The field-by-field return listing is justified because no output schema exists. Core purpose is front-loaded before any detail.

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?

Complete for a 1-parameter list tool. With no output schema, the description documents every return field including served_model null meaning, verdict type, the comparable_to_parent discontinuity flag, and the 200-cap. Auth requirements, gating behavior, and ordering are all disclosed. Nothing an agent needs to correctly call and interpret the results is missing.

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 description coverage is 100% — base_model's 'Filter to one base model's lineage (exact match)' is fully documented in the schema. The description's return-shape listing of base_model adds minor context about what 'lineage' refers to, but it contributes no parameter syntax, format, or filtering semantics beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'List the workspace's model-version chain — one immutable record per completed training round, pinning the judge, curriculum and holdout its verdict depended on'. The downstream use ('pick a version to adopt or roll back to') distinguishes it from siblings like adopt_model_version (which performs adoption) and get_model_version (single-version fetch). Purpose is precise and not confusable with any sibling.

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?

Gives explicit use context: 'use it to review improvement history and pick a version to adopt or roll back to'. This is clear enough to route an agent toward listing rather than adopting or single-getting. However, it never names sibling alternatives explicitly (e.g., 'for a single version use get_model_version') or states when not to use it, so it falls short of explicit when/when-not guidance.

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