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

Annotations already declare readOnlyHint=false and destructiveHint=true, so mutation is covered. The description adds information annotations cannot convey: a referee verdict is returned and devnet test money is paid when the target is met, plus a human-approval requirement. It still does not explain what is destroyed or why the call is non-idempotent, which is a real omission for a destructive write.

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?

A single front-loaded sentence delivers purpose, outcome, payout, and the approval gate with no filler. The semicolon-joined clause structure is dense but readable, though it does compress several distinct facts into one runaway sentence.

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?

This is a destructive, non-idempotent write with five undocumented parameters, no output schema, and no explanation of the returned verdict structure. The description covers intent and consequences but leaves an agent unable to construct a correct call or anticipate failure modes.

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% across five parameters, so the description must carry the burden and largely fails. It only hints that some field carries the proof ('proof file') and says nothing about what 'round', 'code', 'name', 'wallet', or 'session' mean, which of them are optional, or what format they take.

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 concrete verb and resource: submits a milestone's proof file to a referee and returns the verdict, including the payout condition. That is far more specific than the bare name. However, it never distinguishes itself from the near-identical sibling knos_milestone_submit (nor from knos_evidence), so an agent cannot tell which submission tool to pick from the description alone.

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?

Includes one real gating rule, 'ask your human first', which is genuine when-to-use guidance. It stops there: no criteria for when a proof is ready to submit, no distinction from knos_milestone_submit, and no mention of prerequisites such as a signed-in session or wallet.

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