批量开关端口连接

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds the concrete state-changing behavior: enabling or disabling port connections. This is consistent with the annotations, but it does not disclose potential side effects such as active connections being dropped when the port is disabled, nor does it mention the two-call confirmation behavior beyond what the confirm_token schema description already provides.

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 a single, front-loaded, information-dense sentence. It states the action, scope, and resource with no filler or repetition. Every word contributes to understanding the tool's purpose.

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?

Given that the schema fully explains all parameters, including the confirm_token preview flow, and annotations cover the safety and idempotency profile, the description is largely complete for invocation. The main missing element is usage positioning relative to sibling tools, but that is partially captured by the unique purpose statement and is more of a usage-guideline 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?

Schema description coverage is 100%, so the parameters are already fully documented (ids, product enum meanings, use_ip_port toggle, and confirm_token flow). The description adds no additional parameter-level meaning. With complete schema coverage, the baseline of 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?

The description uses a specific verb-resource pairing: '批量开启或关闭' (batch enable/disable) '静态住宅子账号的 IP 端口连接状态' (static residential sub-account IP port connection status). This clearly identifies the action and resource. It does not explicitly name sibling alternatives, but the unique port-toggle action is sufficiently distinct among the sub_account_* siblings.

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 provides no guidance on when to use this tool versus alternatives like sub_account_whitelist, sub_account_set_credentials, or sub_account_update. There is no mention of prerequisites, exclusions, or the confirm_token flow as a usage consideration. The intended context is only implied by the tool name and description.

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