set_cause

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

With no annotations, the description carries the full burden. It does disclose a genuinely useful behavioral trait: the user-set cause takes precedence over model suggestions and future model explanations will not override it, which signals persistence. It omits whether an existing cause is overwritten, who is permitted to set it, and what is returned.

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 short sentences with no filler, and the precedence rule is stated up front. It is appropriately sized for what it covers, though the lack of any parameter or scope statement means the brevity borders on under-specification.

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?

A mutation tool with no annotations, no output schema, and 0% schema description coverage needs more than this. The description never covers input meanings, overwrite behavior, or error conditions, so an agent cannot fully predict the effect of a call.

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% and four parameters exist, so the description must compensate. It only conveys the concept of 'cause' and never explains review_id, number, or the optional reflection field, leaving half the inputs semantically opaque.

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 states a specific verb and resource: confirm or modify the cause of an error for a wrong question (错题的错因), tied to a review item. It is clear enough to act on, but it doesn't differentiate itself from siblings like judge_set or mark_reviewed, which an agent would have to inspect separately.

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 only implied: the tool is for when a user confirms or corrects a cause. There is no statement of when to call this versus judge_set or submit_explanation, and no prerequisites (e.g., must the review exist, must a model suggestion already be present). 'User's choice takes priority' hints at a conflict-resolution context but isn't a routing rule.

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