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

With no annotations, the description carries the full load, and it does disclose one genuinely important side effect: setting ready_for_ruling can trigger the panel to start once both sides are ready or the evidence window ends. That is real behavioral value beyond the schema. However, it omits that this is a write/mutation to a dispute, that a private deal token is required for authorization, whether evidence can be amended or withdrawn after submission, and what the caller gets back.

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 sentence with no filler; the readiness mechanic is stated compactly rather than buried. It is slightly awkward as a fragment and the parenthetical carries a lot of weight, but nothing is redundant.

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 5-parameter mutation with no annotations and no output schema, the definition covers the essentials: inputs, the readiness flag, and the ruling-start consequence. The gaps — authorization via token, whether evidence is immutable once submitted, and the response shape — are notable but not fatal for a single-purpose dispute step.

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 only 40% (only token and deal_id are documented inline), so the description must compensate — and it does, naming all three undocumented parameters: text as the statement, links, and ready_for_ruling with its consequence spelled out. A caller can map every required and optional field to a concrete intent without guessing, which is more than the schema alone provides.

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 is an elliptical noun list — "Statement, links, and optionally say you are ready for the ruling" — with no explicit verb, so the actual action (submitting evidence to an existing dispute) is only recoverable from the title. It does enumerate what the tool takes in, which distinguishes it from unrelated siblings like mm_mark_delivered or mm_send_message, but it never says the evidence goes into a dispute or which dispute.

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 is implied rather than stated: the reader infers this belongs to the dispute flow, and the parenthetical explains that the ruling panel starts when both sides are ready or the evidence window closes. There is no explicit when-to-call, no exclusion such as 'do not use after the ruling is issued', and no pointer to mm_open_dispute or mm_respond_to_ruling as the surrounding steps.

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