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

Annotations only say idempotentHint=true and destructiveHint=false; the description adds the genuinely important behaviors the annotations omit — links is a full replacement of the entire set, and an image safety-check failure aborts the whole write so no fields are persisted. It also discloses that changes go live immediately after confirmation, which is essential context for a profile 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?

Very dense and front-loaded — the write semantics, the links rule, the avatar pipeline and the workflow each occupy one short clause. The telegraphic style (semicolons, arrows, the stray leading '登录;') costs a little readability but nothing is wasted.

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?

Covers auth expectation ('登录'), ordering, atomicity on avatar failure, and the follow-up read (get_my_card) in lieu of an output schema. It never states what happens to fields that are omitted — i.e. whether this is a partial patch for everything except links — which is the one piece an agent still has to guess.

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 57%, so the description compensates by explaining that canOffer is the supply-side axis indexed by search_people and scored by needs matching (write concrete offerings, not adjectives), and that the avatar must come from upload_image_from_url. It says nothing about nickname, location, bio or intro beyond the schema text, leaving part of the coverage gap unfilled.

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?

States a specific verb and resource ('patch 本人公开资料'), and immediately distinguishes the tool's scope from siblings by naming add_profile_link and remove_profile_link as the alternatives for single-link edits. An agent can identify what this tool does and what it doesn't without opening any 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?

Explicitly routes alternatives: full-replacement link edits belong here, single-link edits go to add/remove_profile_link. It also gives an ordered workflow (get_my_profile → confirm changes → update → get_my_card) and a prerequisite for avatar (call upload_image_from_url first). When/when-not guidance is complete.

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