批量改子账号密码

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

Annotations only state readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral context beyond those hints: it does not modify usernames, only supports letter/digit passwords of length 8–30, and rejects system-default credentials. This meaningfully clarifies operational constraints, though it does not cover result or confirmation behavior.

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 two concise sentences with no filler. It front-loads the main purpose, immediately states constraints, and then gives the prerequisite and alternative tool. Every sentence earns its place.

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?

The description provides the core information needed for invocation: target scope, required constraints, and the prerequisite credential setup. The confirm_token flow is left to the schema, where it is fully explained. Without an output schema, a brief note on result/preview behavior could help, but this is a minor gap rather than a blocking omission.

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 baseline is 3. The description's password rule ('密码只能是字母和数字，长度 8 到 30') duplicates the customPassword schema description, and '只改密码不改用户名' is effect clarification rather than new parameter semantics. No substantial parameter meaning beyond the schema is added.

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: '批量修改时长类子账号的密码' (batch modify passwords of duration-type sub-accounts), and explicitly scopes the operation with '只改密码不改用户名' (only change password, not username). It distinguishes itself from the sibling sub_account_set_credentials by naming it as the prerequisite tool.

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 gives explicit when-to-use guidance and an exclusion: it can only change passwords when custom username/password already exist, and '系统默认的账密不能用它改' (default credentials cannot be changed with it), directing the agent to use sub_account_set_credentials first. This clearly separates the tool from the setup flow.

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