get model version

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

Annotations already mark the tool readOnly, idempotent, and non-destructive. The description enriches this with concrete behavioral details: the GET endpoint, API-key scope `read`, the note that it is 'Not feature-flag gated', the OWNER/ADMIN key requirement with a 403 error, and the exact return shape. This significantly exceeds the annotation baseline.

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 front-loaded with the core purpose and only includes high-signal details: use case, endpoint, auth, return shape, and relevant caveats. Every sentence earns its place, and the structured layout makes it scannable.

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?

Despite having no output schema, the description explicitly lists all return fields and states the response shape equals list rows. It covers the endpoint, required permissions, error condition, feature-flag status, and intended workflow, making the context complete for a single-fetch tool.

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 100%; the sole `id` parameter is already described as workspace-scoped with error behavior. The description only mentions `{id}` in the URL path and does not add new meaning to the parameter, so it correctly stays at the baseline for fully covered schemas.

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 uses a specific verb and resource: 'Fetch one model version's record', and it enumerates the contents (lineage, artifact, served model name, verdict, pinned hashes, adoption time). It also differentiates the tool from siblings by framing it as inspecting a specific training round before adopting, making its identity clear.

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 provides a clear usage context: 'use it to inspect a specific training round before adopting it', which implies this is a detail view for one version. It does not explicitly name alternatives like list_model_versions or state when not to use the tool, so it falls just short of full explicit guidance.

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