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

With no annotations, the description carries the full burden and does well: it declares the login requirement, the exact failure signals (401 unauthenticated, code=40003 with data.bindUrl for unbound marketplace instances), and that the call returns the full updated profile plus `created`. The remaining gap is write semantics — it never says whether the save replaces or merges with the existing profile, or what happens to omitted sections, which matters for a mutation over 12 fields.

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-loaded with the login flag and the when-to-call constraint, then caller-specific rules, then return value, then a clearly separated auth section. No filler; the only near-redundant line is the "本体: contact → Action: profile.save" tag.

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 12-parameter mutation with no annotations and no output schema, the definition covers auth, invocation gating, contactid routing, and a return summary — but leaves the payload fields and the replace-vs-merge behavior undefined. An agent could call it correctly in the auth sense yet plausibly destroy existing profile sections.

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 0% across 12 parameters, so the description must compensate, and it only addresses the contactid case (self vs. family resolution) — useful, especially given the ambiguous duplicate contactId/contactid properties in the schema. The ten health-profile payload fields (lifestyle, surgeries, medications, examinations, problem_list, family_history, etc.) get no meaning, expected shape, or example anywhere.

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 (save/update) and a specific resource (long-term health profile), and explicitly distinguishes the case from plan recommendation ("仅推荐方案不得调用"), which names the closest sibling concern. An agent can tell this apart from contact_profile_get and plan_recommend without opening either 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 an explicit trigger (only when the user explicitly asks to save/update a long-term profile), an explicit exclusion (do not call for mere recommendation), and per-caller rules: omit contactid for self, resolve a unique contactid for family members, never write family data into the self profile. When-to-use, when-not, and the alternative are all present.

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