model_metrics

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

The description is rich in behavioral details: it explains that bestEpochMetrics is pulled explicitly from trainResults by matching epoch against bestEpoch, independent of include_history window. It also specifies that on incoherent training data, the tool returns nulls instead of echoing unreliable platform values, and that include_train_args adds a large object (111 keys). Even with annotations indicating read-only and non-destructive, the description adds crucial context about data integrity and return semantics.

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 longer than typical but packed with necessary information. It front-loads the core purpose of distinguishing best vs final epoch metrics, and then elaborates on edge cases and flags. Every sentence adds value, though the length could be slightly trimmed without losing critical context. The structure is logical: purpose, detailed behavior, edge cases, optional parameters.

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's complexity (distinguishing best/final metrics, handling edge cases), the description covers all necessary context. It explains the meaning of null returns, the behavior of include_history and include_train_args, and notes the epoch window reporting. Since there is no output schema, the description compensates well by detailing return semantics. An agent can call this tool correctly without ambiguity.

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 schema already has detailed descriptions for each parameter (100% coverage). The description adds semantics like 'omitted by default' for include_history and include_train_args, and clarifies the meaning of history_last_n's window reporting. It also explains the impact of include_train_args on performance, which goes beyond the schema's 'roughly a hundred keys'.

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 reports a model's best-epoch and final-epoch evaluation metrics, with a specific verb and resource. It explicitly differentiates the two metric sets, which is critical for agent understanding, and mentions it works for private and public projects. It stands out from sibling tools like model_plots and training_monitor because of this precise focus on epoch-level metrics, including handling of edge cases.

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 implies usage: when you need a model's evaluation metrics at best and final epochs, especially to avoid confusion between the two. It also explains conditions like include_train_args and include_history, but does not explicitly say 'use this instead of X' or 'when not to use'. The context is clear, but exclusions and alternatives to siblings could be more explicit.

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