duplicate_memory

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing concrete side effects: 'Writes to local disk and appends to the change timeline,' original untouched, copy gets its own history, and the exact failure behavior on second call. This adds valuable context about mutations, safety (expected_hash), and project pinning behavior.

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?

Although longer than typical, every sentence earns its place. The structure is logical: core action, side effects, usage alternatives, idempotency warning, parameter explanations, project_path nuance, and return value. No redundancy or filler; information is dense but well-organized.

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?

With no output schema, the description correctly specifies the return object ('address, path, content_hash, and revision id'). It also covers critical context such as project_path behavior, expected_hash safety, the divergence behavior, and failure mode, making it fully complete for a mutation tool of this complexity.

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 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds meaning by noting new_relative_path 'must not already exist' and explaining expected_hash as a guard against copying unseen revisions, providing slightly more context than the schema alone.

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: 'copy one curated memory file to a new path under a new stable identity.' It clearly distinguishes from siblings by stating 'Use move_memory instead when the original should not survive,' and reinforces the copy semantics by explaining divergence and independent histories.

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 states when to use ('Use it to fork an existing memory into a variant') and when not to ('Use move_memory instead when the original should not survive'). Also provides operational guidance on project_path omission and warns against non-idempotent double calls, giving clear context and exclusions.

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