Finalize Session

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description is consistent with these — no contradiction. The description adds useful context about the operator token and host requirement beyond the annotations. However, it misses the most agent-relevant behavioral details for a state-mutating operation: whether finalization is terminal, whether it can be resumed, what happens to in-flight rounds, and what the return looks like. Annotations lower the bar, but the description still leaves side effects undisclosed.

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 sentences with every clause earning its place; the operator scope is front-loaded ahead of the action, and the token/host requirement is packed into the second sentence. The only minor waste is restating the 200-character reason limit that already exists in the schema's maxLength constraint. Otherwise remarkably tight for the amount of information conveyed.

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 moderate-complexity mutation tool with no output schema, the description covers the core operation and access model competently. However, with no output schema to document return values, the burden on the description rises, and it leaves unexplained: whether finalization is terminal, the return/confirmation format, and error behaviors (e.g., unknown session_id, finalizing an already-finalized session). The absence of any guidance on interaction with concurrent rounds is notable given siblings like session_recover_interrupted.

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?

With 0% schema description coverage, the description bears a heavy burden, but it adds almost nothing beyond restating the 200-character reason cap already present in the schema's maxLength. It offers no guidance on the semantics of choosing among 'converged' vs 'aborted' vs 'max-rounds', does not disambiguate the confusing 'caller' enum (listing model names with default 'operator'), and is silent on session_id state requirements and response_format. For a tool with low schema coverage, this is a significant gap that the description fails to compensate for.

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 provides a specific verb ('mark'), a resource ('a durable session'), and the exact set of outcome values ('converged, aborted or max-rounds'), leaving no ambiguity about what the tool does. The 'Operator-only' scoping and title align tightly with the name. However, it doesn't explicitly differentiate itself from the 28 siblings (e.g., session_cancel_job, session_start_round), even though such differentiation would be valuable, keeping it at a 4 rather than 5.

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 gives meaningful contextual constraints — 'Operator-only' and 'Requires the dedicated operator capability token from a separate human-console host' — which effectively tell the agent when it can and cannot call this tool. However, it provides no explicit routing to or exclusion from alternatives, which matters given the large sibling set. The usage guidance is implied through access prerequisites rather than stated as when-to-use vs. when-not-to-use guidance.

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