reopen_contract

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

With no annotations, the description carries the burden and it names concrete behavioral side effects: resetting to drafting, unbinding the acceptor, and clearing verifications. It stops short of explaining reversibility, audit/notification effects, or failure modes, but the core destructive behavior is disclosed. 'Loud' hints at observability but is left undefined.

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 extremely compact and front-loads the most important qualifier ('integrator-only') and action. The semicolon-separated side effects are efficient, though 'loud' could be clarified without adding length.

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-required-param mutation with no annotations and zero schema descriptions, a single sentence is insufficient. The agent cannot determine parameter semantics, usage conditions, or full consequences; the output schema helps with return shape but not with calling correctly.

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 0%, so the description must explain the five required parameters; it only implies actor_role='integrator' through 'integrator-only.' contract_id, base_revision, reason, and actor_id remain unexplained, especially the revision-checking purpose of base_revision and why reason is required.

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 distinct action—'reset to drafting'—on the contract resource and explicitly lists side effects ('unbinds acceptor, clears verifications'), separating it from accept_contract, seal_contract, and reject_contract. The term 'loud' is jargon but does not obscure the core purpose.

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 only usage signal is 'integrator-only,' which restricts who may call it but not when. It does not state conditions for resetting to drafting, contrast with reject_contract or waive_deviation, or mention prerequisites.

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