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

Annotations already declare idempotentHint=true and destructiveHint=false; the description reinforces this with '已撤幂等' and adds context the annotations do not carry — login requirement, a pre-revoke confirmation, that the receipt returns the remaining list, and that making a fact PUBLIC needs explicit confirmation. No contradiction with the annotations, though it does not state whether a revoked preference can be restored.

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?

Compact and front-loaded: the login gate appears first, then the core action, the disambiguation, and the prerequisite chain. Bracketed markers structure it well; density is high but each clause carries meaning.

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 output schema, it covers the important gaps — auth, idempotency, confirmation, return content, and the prerequisite discovery call — enough for correct invocation. Reversibility and ownership/permission scope beyond login are left unstated.

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%, so both id and the visibility enum are already documented, establishing the baseline of 3. The description reinforces the omit-visibility-equals-revoke behavior and the id source, but adds no syntax or constraint detail beyond what the schema already 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?

States a specific verb (撤销/revoke) and resource (匹配偏好), and explicitly distinguishes it from the visibility-changing operation on positioning facts, so an agent can separate it from set_my_match_preference. Minor ambiguity: the visibility parameter actually performs a visibility change, which slightly blurs the stated 'revoke differs from visibility change' framing.

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?

Gives real context: login required, a confirmation step before revoking, an explicit prerequisite chain (list_my_match_preferences → revoke), and the practical warning to clear expired items first to avoid the 20-item cap. It does not spell out explicit when-not-to-use conditions beyond the visibility distinction.

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