Amber

Official

by ambermem

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

List existing subjects (people)

amber_list_subjects

Read-onlyIdempotent

Lists people stored in memory with mention counts and related topics, ordered by mention count, so you can reuse existing subject spellings before storing or searching memories.

Instructions

List the subjects (people) already in memory, most-mentioned first, with a count and the topics their memories appear under. Call this before amber_store_memory or amber_search_memories when you're unsure how a person was recorded, and REUSE the existing spelling ("patrick vane") instead of a near-duplicate ("pat"/"patrick"/"patrick v"). Subject drives retrieval ranking, so consistent naming matters even more than for topics.

USE topics TO CATCH A SPLIT PERSON. Subjects match by EXACT text, so one human recorded under two names (a nickname, a maiden name, a first name then a full name -- e.g. "katie" and "yu pan") forks silently into two people, and every later search returns a plausible but INCOMPLETE answer. String similarity cannot catch that, because the two spellings need not share any characters. Overlapping topics are the signal: two subjects that both appear under e.g. "relationships" may be the same person. If you suspect a fork, confirm it with the USER (never merge on your own inference -- wrongly merging two real people is worse than the fork), then repair it with amber_rename_subject, which merges into the target name.

Read-only, not rate-limited. Requires an active subscription.

Input Schema

Name	Required	Description	Default
`limit`	No	Max subjects to return (default 200), most-mentioned first.

Output Schema

Name	Required	Description	Default
`has_more`	Yes	True when more subjects exist than were returned. Raise `limit` to see them. Without this a truncated list is indistinguishable from a complete one, and those mean opposite things: `amber_search_memories` tells you to check here for the exact spelling of a name, so "not in this list" has to be trustworthy.
`subjects`	Yes	Existing subjects, most-mentioned first.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.1.6Nov 5, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context they do not carry: 'not rate-limited' and 'Requires an active subscription.' It also discloses the critical behavioral trait that subjects match by EXACT text and that forks produce silently incomplete search results.

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 core action and the reuse-existing-spelling rule are front-loaded, and every paragraph is on-topic. The fork-detection section is long relative to a one-parameter list tool, but it carries genuinely non-obvious guidance rather than filler.

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?

An output schema exists, so return values need not be spelled out, and the description still covers ordering, the count/topics payload, the subscription prerequisite, and the exact-match pitfall. Nothing an agent needs to call this correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and the single `limit` parameter is fully documented in the schema, including default and ordering. The description only echoes the 'most-mentioned first' ordering, adding no new syntax or constraint beyond the schema, so the baseline 3 applies.

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 ('List the subjects (people) already in memory') plus ordering ('most-mentioned first') and return shape ('a count and the `topics`'). It is clearly distinguishable from siblings like amber_search_subjects and amber_list_topics.

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?

Explicitly says to call it before amber_store_memory or amber_search_memories when unsure how a person was recorded, and names amber_rename_subject as the repair path. It also gives a concrete when-to-use signal for the `topics` field (detecting split subjects) and an explicit prohibition (never merge on your own inference).

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