Amber

Official

by ambermem

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Search subjects (people) by name

amber_search_subjects

Read-onlyIdempotent

Search stored people by name fragment to find a subject and its memory count without listing every subject. Supports contains, prefix, suffix, and anchored matching; empty query returns all.

Instructions

Find subjects (people) already in memory WITHOUT listing them all. Same data as amber_list_subjects -- name, memory count, and the topics their memories appear under -- just filtered. Prefer this over amber_list_subjects once a store has grown: listing every subject with its topics costs thousands of tokens on every store, and you usually only need to check one person.

MATCHING -- one rule: NO * means CONTAINS, and * is an anchor. • vane -> contains: finds "patrick vane" AND "robin vane" • van* -> starts with • *vane -> ends with • patrick*vane -> starts with one, ends with the other • * or an empty query -> everything (same as amber_list_subjects) Case- and accent-insensitive: andre finds "andré bremer". Spaces, hyphens, apostrophes and periods are IGNORED on both sides when comparing, so vanderberg and van-der berg both find "van der berg". Word ORDER still matters: berg van does NOT match it. Anchors apply to that compared form, so *jr DOES match "van der berg jr." -- the trailing period is not part of what is compared.

IT MATCHES TEXT, NOT PEOPLE. It cannot tell you that "pat" is "patrick vane" -- unrelated spellings of one human (a nickname, a maiden name) share no characters, so no text search finds them. To catch a person split across two names, list subjects and compare their topics, as amber_list_subjects explains.

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.
`query`	Yes	Name fragment to look for. No `` = contains. `van` = starts with, `vane` = ends with. Empty or `` returns everything.

Output Schema

Name	Required	Description
`has_more`	Yes	True when total_matched exceeds the returned page.
`subjects`	Yes	Matching subjects, most-mentioned first.
`total_matched`	Yes	How many subjects matched in total, BEFORE `limit` was applied. Greater than subjects.length means the list is truncated.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.1.6Nov 5, 2026

TDQS

A4.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds genuinely new operational facts — "not rate-limited" and "Requires an active subscription" — which is real value beyond the annotations, but it says nothing about result ordering or truncation behavior beyond what the schema states.

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?

Front-loaded purpose sentence, then clearly delimited MATCHING and limitation sections with bulleted examples — easy to scan. It runs long and repeats the "same as amber_list_subjects" equivalence twice, but the length is buying disambiguation 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?

For a two-parameter search tool with an output schema, the description covers everything an agent needs to call it correctly: matching semantics, fallback path, rate-limit and subscription prerequisites, and an explicit statement of what the tool cannot do. No material gap remains.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning the schema does not: normalization rules (case- and accent-insensitive, spaces/hyphens/apostrophes/periods ignored on both sides, word order still significant) and worked examples. The only gap is the `limit` parameter, whose semantics are left entirely to the schema.

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?

Opens with a specific verb and resource plus scope: "Find subjects (people) already in memory WITHOUT listing them all," and immediately states the returned fields (name, memory count, topics). It names the sibling amber_list_subjects and explains precisely how the two differ (filtered vs. full listing).

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 routes the agent: "Prefer this over amber_list_subjects once a store has grown," with a token-cost rationale, and gives a reverse condition too — when text matching cannot resolve a person, fall back to listing subjects and comparing `topics`. Both when-to-use and when-not-to-use are covered.

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