Amber

Official

Overview Schema Source Related Servers Discussions Admin

Rename a subject (person) everywhere

amber_rename_subject

Relabel a person across every memory tagged with them when a name changes or expands, merging all existing facts onto one exact-match subject so retrieval no longer misses outdated or partial names.

Instructions

Relabel a subject (person) across EVERY memory tagged with them -- use when a name changes, or when you learn more of it (you stored facts under "sean" and later learn it is "sean okafor"). Subject retrieval is EXACT-MATCH, so a bare first name or an outdated name is a latent retrieval miss; this fixes all of that person's memories at once. If some of those memories already carry new_subject, they MERGE onto the one name -- merged_into_existing reports how many. NEVER deletes a memory. A plain rename (target name unused) is fully reversible by renaming back. A MERGE IS NOT REVERSIBLE: once two names are one, renaming back moves ALL of those memories to the old name, including the ones that never had it -- the original split cannot be restored through this tool. So when merged_into_existing would be > 0 you are performing a ONE-WAY operation: be correspondingly sure, and prefer confirming with the user first. Both names match case-insensitively and are normalized the same way stored subjects are (call amber_list_subjects to see exact spellings first). Also relabels the person on any of their memories currently in the trash, so restoring one later stays consistent -- so renamed_count (total memories relabelled) can exceed the active count shown by amber_list_subjects. Returns renamed_count; 0 (a no-op, not an error) if no memory was tagged with old_subject. Requires an active subscription.

Errors: invalid_input (a name is empty, too long, or carries control characters).

Input Schema

Name	Required	Description	Default
`new_subject`	Yes	The corrected / updated full name, e.g. "sean okafor".
`old_subject`	Yes	The subject as currently stored, e.g. "sean" (case-insensitive; check amber_list_subjects).

Output Schema

Name	Required	Description
`status`	Yes	Always `renamed`, including when `renamed_count` is 0. Matching nothing is a no-op rather than a failure.
`new_subject`	Yes	The normalized new subject applied.
`old_subject`	Yes	The normalized old subject that was matched.
`renamed_count`	Yes	Total memories relabelled from old_subject to new_subject (active + trashed).
`renamed_active`	Yes	How many of renamed_count were ACTIVE memories -- this is the number that matches what amber_list_subjects reports.
`renamed_trashed`	Yes	How many of renamed_count were in the trash. Trashed memories are relabelled too so a later restore stays consistent; this is why renamed_count can exceed the active count.
`merged_into_active`	Yes	Of merged_into_existing, how many are ACTIVE -- this is the figure that reconciles with amber_list_subjects, which counts active memories only.
`merged_into_trashed`	Yes	Of merged_into_existing, how many are in the trash. Trashed rows are counted because they are relabelled too, which is why the total can exceed what amber_list_subjects shows.
`merged_into_existing`	Yes	Memories that ALREADY carried new_subject before this call, counting any that carried BOTH names (on those the two tags simply became one). When >0 the two names are now one person, not a plain rename -- surface that to the user, since merging two genuinely different people is hard to notice and worse than leaving them split.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.1.6Nov 5, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well past the annotations, disclosing merge behavior, the irreversibility of a merge, that deleted memories are also relabelled (so renamed_count can exceed the active count), that a no-op returns 0 rather than an error, the subscription requirement, and the invalid_input conditions. The destructiveHint=false annotation is consistent with the stated "NEVER deletes a memory"; the description productively refines that by explaining that irreversibility arises from merging, not deletion.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the exact-match retrieval rationale are front-loaded, and the risk disclosure follows in a logical order. It is a dense block of prose with some repetition around the merge warning, so it is efficient rather than optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with an output schema already present, the description covers everything an agent needs: when to call it, what it returns, what it touches (including trashed memories), what is reversible, and what error to expect. Nothing material is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema coverage at 100% the schema already documents both parameters, so the baseline is 3. The description still adds real meaning: shared case-insensitive matching and normalization of both names, plus the invalid_input failure modes (empty, oversized, control characters) that the schema does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Relabel a subject (person) across EVERY memory tagged with them") and makes the scope explicit, which separates it cleanly from amber_list_subjects, amber_search_subjects, and amber_update_memory. The parenthetical example of a first name becoming a full name removes any ambiguity about what 'rename a subject' means in practice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives both trigger cases (a name changed, or you learned more of it) and names the prerequisite alternative, amber_list_subjects, for confirming exact spellings. It also supplies an exclusion-style warning: when merged_into_existing would be > 0, be sure and confirm with the user first, which is actionable decision guidance rather than generic advice.

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