void_contract

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

With no annotations provided, the description carries full burden and fully delivers. It specifies the exact side effects: 'active=false, voided_at=now(), void_reason=...' and that the contract exits current contract selection. It discloses idempotency behavior, stating repeated calls return the voided state without error, second write, or overwriting the original void_reason. This is comprehensive behavioral disclosure.

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 front-loaded with the most critical prerequisite (consent) and then compactly covers the effect, idempotency, and relationship to the read model. Every sentence earns its place; there is no fluff or repetition of schema content.

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 mutation tool with no annotations and no output schema, the description covers prerequisites, exact side effects, idempotency, and even references the implementation file (lib/currentContract.ts) for affected read paths. It is complete enough for an agent to correctly select and invoke the tool.

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 100%, and each parameter already has detailed semantics (e.g., reason is the original text to show, learner_consent must be the learner's verbatim words, idempotency_key for retries). The description adds workflow context but does not materially extend the per-parameter meaning beyond the schema, so a baseline score of 3 is appropriate.

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 uses the specific verb '作废合约' (void contract) and clearly defines the resource as a teaching contract. It distinguishes the behavior from deletion by stating '作废不是删除——合约行原样保留' (void is not delete—the contract row is preserved), which sets it apart from a destructive delete and implies it is a state transition. This is clear and differentiates from sibling tools like complete_contract in effect.

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 provides strong usage context: it mandates that the reason must be shown to the learner and consent obtained before calling, and states that unauthorized calls are a violation ('未经同意调用属违纪'). It also clarifies that this is not a deletion operation. However, it does not explicitly name alternative tools (e.g., complete_contract) or state when to prefer voiding over completing, so it lacks an explicit exclusion for those alternatives.

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