CPersona

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

Beyond annotations (idempotentHint: true, readOnlyHint: false), the description adds valuable behavioral details: it discloses atomicity ('one-shot'), explains deduplication logic for the 'skip' strategy (msg_id for memories, summary for episodes), and clarifies the file-less workflow. It does not mention idempotency explicitly, relying on annotations for that.

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?

Two dense sentences with zero waste. The first sentence front-loads the core action and unique value proposition (atomic, no intermediate files). The second sentence provides specific deduplication mechanics. Every word earns its place.

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 complex data migration operation with 5 parameters, the description covers the critical behavioral aspects (atomicity, deduplication, copy vs. move semantics). It appropriately delegates parameter specifics to the comprehensive schema. Minor gap: lacks mention of error conditions or agent existence prerequisites.

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?

With 100% schema coverage, the baseline is 3. The description elevates this by adding semantic depth for the 'strategy' parameter (explaining deduplication mechanics) and contextualizing 'mode' within the export/import equivalence. It adds meaningful value beyond the schema's technical definitions.

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 uses a specific verb ('Merge') with specific resources ('memories, episodes, and profiles') and explicitly distinguishes this tool from siblings by positioning it as an 'atomic one-shot equivalent of export→import without intermediate files,' clearly differentiating from export_memories and import_memories.

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 clear comparative context against the export→import workflow, helping agents choose this for atomic operations without file intermediates. However, it lacks explicit 'when not to use' guidance or prerequisites (e.g., whether both agents must exist beforehand).

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