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

Annotations provide readOnly=false and idempotentHint=true, but the description adds substantial behavior: requires login, affects three recommendation layers, re-writing same sentence changes scope, server normalizes/truncates to 60 chars, drops command-like input, returns recorded/scopeDowngraded/capped fields, and enforces a 20-preference cap. No contradiction with annotations.

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 organized into four labeled sections, each containing distinct operational instructions. Purpose is front-loaded, and no sentence is filler. Slight repetition of '这会改系统' is minor compared to the density of useful guidance.

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?

Even without an output schema, the description covers return-status interpretations (recorded=false, scopeDowngraded=true, capped non-empty), authentication requirement, interaction with sibling tools, and server-side text handling. An agent has everything needed to invoke and interpret this tool 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 100% and every param (polarity, scope, days, needId, text) already has a clear description. The tool description adds only an example of user phrasing and a duplicate warning about command-like words, which does not meaningfully go beyond the schema. Baseline 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?

States a specific verb '记成' (record) and resource '破冰匹配偏好', with explicit effect '直接改变下一轮'. It also distinguishes itself by warning '别为「改成长期」另找工具', and implicitly differentiates from siblings like pause_need_icebreak and list_my_match_preferences.

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 '【组合链】' section explicitly names list_my_match_preferences as a prerequisite, and provides an exclusion: '只想停某条需求别写偏好，用 pause_need_icebreak'. It also tells the agent not to search for another tool for changing scope, giving clear when-to-use guidance.

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