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

Annotations declare writability and non-idempotency, but the description adds material context beyond them: auth requirement, that the write is an append rather than destructive replacement, the per-type privacy defaults, the need to explicitly confirm public exposure of contact data, and the downstream audience ('公开内容可被get_creator看到'). This is exactly the extra behavioral surface an agent needs for a privacy-sensitive mutation.

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?

Front-loads the login gate and the non-overwrite guarantee, then brackets the defaults and chain, so the highest-value facts come first. It is dense with little waste, though the visibility-default list largely restates the schema's own description of that parameter.

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 4-param mutation tool with no output schema, it covers auth, side effects, default derivation, exposure consequences, and follow-up calls. Nothing an agent needs to invoke it correctly is missing.

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 already 100%, so baseline is 3. The description reinforces parameter meaning by tying the visibility enum to type-specific defaults (phone=PRIVATE, IM apps=FRIENDS, others=PUBLIC) and stressing the explicit-public requirement, adding operational nuance beyond the schema text.

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?

Names a specific verb+resource (追加本人链接 = append own profile link) and adds the discriminating scope detail '不覆盖其余' (does not overwrite existing links), which cleanly separates it from sibling remove_profile_link and set_link_visibility. An agent can route correctly without opening the schema.

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?

Gives clear context: login required, per-type default visibility, and an explicit conditional ('要公开联系方式必须显式传 public'). It also sketches a workflow chain (get_my_profile→添加→get_my_card). It stops short of naming set_link_visibility/remove_profile_link as the alternative for modifying or deleting an existing link, so guidance is strong but not exhaustive.

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