ncloud_mailer_create_address_book

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

Beyond the annotation (destructiveHint: false), the description discloses critical behavioral traits: asynchronous processing (response reflects pre-request state), append behavior for existing groups, and the suggestion to re-read. It also flags the legacy/limited availability. No contradiction with annotations; adds significant transparency.

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: it leads with legacy context in brackets, then the core action, then append and async notes. It is information-dense but not bloated; each sentence earns its place. Could be slightly tighter, but it is appropriately sized and front-loaded.

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 no output schema, the description covers purpose, append behavior, async nature, and re-reading. It does not explain error cases or permissions, but for a create/add tool these are not essential. The schema already documents dryRun and region. It is sufficiently complete for an agent to call it 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%, so parameters are documented. The description adds value by explaining that an existing groupName appends to that group (not in schema) and that processing is asynchronous. It does not redundantly repeat schema descriptions but adds behavioral nuance relevant to parameters.

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 operation: 'Add recipient groups and/or addresses to the address book (POST /address-book)'. It also distinguishes itself from siblings by noting it is the legacy Cloud Outbound Mailer API and names the new alternatives for mail sending/lookup. The verb 'add' and resource 'address book' are specific, and the append behavior is highlighted.

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 context: it is legacy, available only to migrated projects, and points to ncloud_sens_send_mail / ncloud_sens_list_mail_requests for new mail sending/lookup. It implicitly says not to use this for new projects. It also advises re-reading with ncloud_mailer_get_address_book due to async processing, but does not explicitly compare with other address-book tools like delete. Overall, clear usage context with an exclusion.

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