check_completion

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

With no annotations provided, the description carries the full burden. It does disclose the key behavioral trait — "Always returns instantly" — which tells the agent this call never blocks, plus the content of the response. It does not disclose error behavior for an invalid or unknown run_id, but an output schema exists to document the return structure, so the main non-blocking trait being disclosed is meaningful context.

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?

Two tightly written sentences with zero waste. The purpose is front-loaded, the key non-blocking behavior is in the first sentence, the return contents in the second, and the Args section is clean and minimal. Every sentence earns its place.

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 simple one-parameter, non-blocking check tool with an output schema, the description covers the essentials: what it does, that it returns instantly, what values it reports, and the parameter meaning. The main gap is the lack of explicit routing to sibling alternatives like wait_for_completion (for blocking until done) or check_step/check_reward (for individual values), which would improve orientation given the large sibling list.

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 0%, so the description must compensate. The Args section says "run_id: The run to check," which adds real semantics beyond the schema's tautological "Run Id" title. It fully explains the parameter's purpose, though it omits format details such as whether the ID is a UUID or a run name.

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: "Check if a training run has finished," and clarifies the scope by listing what it returns (status, step, reward, completion). It distinguishes itself from focused siblings like check_step and check_reward by being an aggregate check, and from wait_for_completion by emphasizing it "returns instantly," but it never names any sibling explicitly.

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?

Usage context is implied rather than stated. "Always returns instantly" signals that this is a non-blocking poll-style call, implicitly contrasting with the sibling wait_for_completion, and the aggregate return values imply you don't need separate check_step or check_reward calls. However, there is no explicit when-to-use or when-not-to-use guidance or named alternatives.

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