save_card

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the tool's core value (compressing a long conversation into a short card), discloses that anchors are automatically merged server-side, and specifies a post-call confirmation message to show the user. This is behaviorally informative without annotations.

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 front-loaded with purpose and trigger timing, followed by a clean type-by-type breakdown. It is fairly long, but the length is justified by the need to define three distinct card types and their field semantics. A slightly tighter structure could improve scannability, but there is little waste.

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 creation tool with 9 parameters, 4 required, and no output schema, the description covers what the tool does, when to trigger it, how to map conversation content into fields, and what to output after saving. It also explains the optional ctx coordinates and the anchoring behavior, so an agent has enough context to invoke 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it maps each card type to specific field interpretations, gives constraints like checks 2-4 items with verb-first steps, anchors 1-4 words, and clarifies that symptom/checks/rootCause mean different things per type. This is far beyond a baseline schema-only definition.

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 opens with a specific verb and resource: '沉淀成卡' (distill into a card) when AI collaboration produces content worth long-term memory. It further defines three concrete card types (debug, knowledge, decision), making the tool's purpose unambiguous and distinct from sibling tools like search_cards, review_card, or delete_card.

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 gives explicit trigger conditions: call proactively after solving a bug, explaining a concept, or making a decision; also trigger on user phrases like '存一下', '今天就到这', or '收尾'. It covers when to use the tool well, though it does not explicitly state when not to use it or name alternative sibling tools.

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