修改群成员班级昵称

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

Annotations indicate this is a write, idempotent, non-destructive operation, and the description goes beyond this by explaining the exact transformation: it replaces group nicknames (defaulted to user nicknames) with the institution backend's 'student name'. It also discloses the effect on IM group and classroom displays, adding useful behavioral context without contradicting any 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 well-structured with clear sections (功能说明, 使用场景, 参数, 返回), front-loaded with the primary purpose. Every sentence contributes meaningful context without redundancy, and the length is appropriate for the tool's complexity.

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 simple mutation tool, the description provides thorough context: how class groups are created, why this modification is needed, when to invoke it, and what is affected. The return value is vaguely described as '成功返回操作结果', but given the lack of an output schema and the simplicity of the operation, this is not a significant gap.

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?

Input schema coverage is 100% with detailed descriptions for both courseId and response_format. The tool description's parameter section only repeats 'courseId: 课程ID', adding little beyond the schema, though the functional explanation helps clarify the course-group relationship. Baseline 3 is appropriate since the schema carries the semantic load.

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 clearly states the tool's purpose: '批量修改课程班级群中所有学生和旁听生的班级昵称' (batch modify class nicknames for all students and auditors in a course class group). It uses a specific verb (modify), identifies the resource (class group member nicknames), and defines the scope (all students and auditors), which distinguishes it from other modify tools in the sibling list.

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 includes a dedicated '使用场景' (usage scenario) section explaining when to use the tool: to resolve mismatches when students change their user nicknames in ClassIn, and recommends calling it after creating a course and adding students/auditors. This provides clear context, though it does not explicitly mention when not to use it or alternatives.

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