Skip to main content
Glama

Search memories

amber_search_memories
Read-onlyIdempotent

Search persistent memories by natural-language question or description to recall user facts and events; add synonyms and exact terms to sharpen matches.

Instructions

Find active memories by semantic meaning. Write the query as a natural-language question or description, NOT as keywords. Good: "What are the user's dietary preferences?", "meetings the user had last week". Bad: "diet food preferences", "meeting notes". Recall depends on YOU expanding the query: pass alternative phrasings in query_variants (synonyms, related terms, and sub-questions), the same way you attach variants when storing. Amber searches the query plus every variant and fuses the results -- it does NOT expand the query for you. For exact-term precision, also pass the distinctive lexical terms the answer would contain (key nouns, product names, numbers, IDs) in keywords -- and OMIT the subject's name from them (use subjects for that). Supports optional metadata filtering (e.g. { "user_tag": "work" }). Results are ordered by relevance (higher score = better match). Scores are only meaningful for ranking within a single query, not across different queries. IMPORTANT -- results are RANKED, never FILTERED: Amber always returns the closest n_results memories it has, even when none of them actually answer the query. A returned memory is therefore NOT evidence that the answer is stored, and a low score is not a reliable absence signal (scores aren't comparable across queries). YOU must judge relevance by READING the content: if no returned memory actually states the fact you asked about, treat it as NOT in memory. This matters most for the mandatory search-before-store check -- only count a fact as already stored when a returned memory genuinely states it, not merely because results came back. Ask for fewer results (n_results) if the padding is noisy. Use amber_list_memories for chronological browsing. When several results describe the SAME subject at different points in time, read them as a TIMELINE of how it evolved -- a more recent memory updates an older one, it does NOT contradict it. Each result carries created_at (and event_start/event_end when known); use those timestamps to order the progression rather than treating differing facts as a conflict. Optional topics param: pass topic names (like when storing) to focus on a category -- matched SEMANTICALLY against topics that already exist, so "beliefs" also matches "opinions"/"superstitions". It restricts the SEMANTIC half of the search to memories under the nearest topics and gives closer ones a BOUNDED lift (at most 1.5x) -- it does NOT re-sort by topic, and the keyword half is not restricted, so off-topic memories can still appear. Do not expect the on-topic memory at #1: a memory that answers the query better still wins, which is deliberate (a wrong topic guess must never bury the true answer). There is NO similarity floor: your name is matched to the NEAREST existing topics whatever their similarity, so a name matching nothing conceptually still resolves to the closest topics rather than to none. Check topics_resolved -- it reports the similarity of each match, and a low number there means your name found nothing real. A poor match cannot bury the true answer, because the lift is bounded and the keyword half is never restricted, but it does not silently become a no-op either. Omit if unsure. Content is truncated to 1000 chars in search results -- use amber_get_memory for full content. Rate-limited (drip bucket: 5000 capacity, refills ~1 token per 17 seconds).

Errors: invalid_input (a parameter has the wrong type, or a date could not be parsed). An empty result is NOT an error and comes back as an ordinary response with no hits. It is also RARE, because ranking pads results rather than filtering them, so treat it as "this account has nothing to rank" -- a new or emptied store, or a metadata_filter that excluded everything -- rather than as a stronger absence signal than a padded result.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>",
      "subjects": "<subjects>"
    },
    "name": "amber_search_memories"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesNatural-language question or description of what to find. Use full sentences, not keywords.
topicsNoOptional topic hint. Pass category names like 'food', 'work', 'beliefs'. What it actually does, in order: (1) each name is matched SEMANTICALLY against the topics that already exist and have live memories -- 'hobbies' resolves to 'gaming'; (2) the SEMANTIC half of the search is restricted to memories carrying one of the ~10 nearest topics, so on a store with many topics this genuinely narrows, while on a small store it may narrow nothing; (3) the keyword half is NOT restricted, so an off-topic memory can still appear via an exact word match; (4) closer topics get a bounded lift of at most 1.5x. That lift is a TIE-BREAKER and will NOT override relevance: a result scoring clearly better on the text still wins, so do not expect the on-topic memory to jump to #1. A synonym's edge over a near-neighbour topic is only a few percent; an EXACT existing name is far stronger. So if you need the topic to actually decide the order, call amber_list_topics and pass the exact name. The response reports `topics_resolved` -- what each name you passed matched -- so you can see how it was interpreted instead of guessing. A name matching nothing leaves the ranking unrestricted. Omit if unsure.
keywordsNoOptional EXACT lexical terms for the keyword (full-text) side of hybrid search -- the distinctive words the answer would contain: key nouns, product names, numbers, IDs, codes. E.g. for "what car does the user drive?" pass ["car", "drive"]. Pick them yourself and OMIT the subject's name (that's what `subjects` is for -- a name matches every fact about a person and only adds noise). If omitted, Amber extracts keywords heuristically. Semantic matching still runs on the query + query_variants; keywords only sharpen exact-term precision.
subjectsYesREQUIRED. Who is this query about? An ARRAY -- usually ONE person, e.g. ["patrick vane"]. Routes ranking so the right person's facts surface. Use ["self"] (or ["me"]) when the query is about the USER (e.g. "what foods is the user allergic to?") -- lifts the user's OWN facts above facts about family or others. Use a person's FULL name (e.g. ["patrick vane"]) when the query is about them: subjects are matched by EXACT (case-insensitive) text, so it must match how they were stored -- a bare first name can miss them or hit a different person. Call amber_list_subjects to see the exact names already stored. Use ["anyone"] or [] for a general query with no personal focus (e.g. "good pasta recipes"). List several only when the query is genuinely about multiple people together. BOOSTS matching memories, never hard-filters -- other subjects still appear, lower down.
n_resultsNoMaximum number of results to return (default 10, max 100).
near_dateNoOptional ISO 8601 datetime to rank results by TEMPORAL PROXIMITY to -- memories whose own event time (event_start/event_end) sits closest to this rank higher. Use it when the query has a time focus that plain wording can't resolve: for "where does the user work NOW?" pass today's date so the current job outranks an older one; for "what car did they drive back in 2019?" pass "2019-01-01". Memories with no event date keep their relative order among themselves, though their absolute scores move slightly (measured: about 10% lower under any anchor, because anchoring renormalises the whole result set), and a far-in-time memory is never pushed BELOW an unboosted peer, though its absolute score drops 5-10% under renormalisation -- the ordering claim holds, the score claim did not, and this sentence used to make the stronger one. Pass it whenever the question genuinely has a time focus -- ESPECIALLY for relative-time wording ("recently", "lately", "last week"), because that wording carries no meaning the text search can match, so the anchor is the only thing that can find the right memory. Do NOT pass it for a time-agnostic question: dated memories can then surface above undated ones that answer it better. Omit when in doubt.
near_date_endNoOptional ISO 8601 datetime. When set together with `near_date`, proximity is measured to the WINDOW [near_date, near_date_end] instead of a single instant (a memory whose event overlaps the window gets the full boost). Use for period queries like "what happened during 2023?" (near_date 2023-01-01, near_date_end 2023-12-31). REJECTED with invalid_input if `near_date` is not also given -- it marks the end of a window, so on its own it is a mistake rather than something to silently drop. Must be on or after near_date.
query_variantsNoAlternative phrasings of the SAME query that YOU generate -- synonyms, related terms, and any sub-questions -- exactly like the variants you attach when storing. Amber embeds and searches every one and fuses the results, so a memory worded differently than the user's phrasing still surfaces. Example: for "what does the user eat?" pass ["the user's dietary preferences", "foods the user likes", "what food does the user avoid?"]. Aim for 3-6; this replaces the automatic query expansion Amber used to do server-side.
metadata_filterNoOptional EXACT-match metadata filter. Matches memories whose metadata contains every key-value pair given. Matching is TYPE-STRICT: metadata stored as the number 5 is matched by 5, NOT by "5". A null VALUE matches only memories that explicitly stored a null under that key -- a memory missing the key entirely does NOT match. Values must be SCALARS (string/number/boolean/null) -- operator objects like {"$ne": ...}/{"$gte": ...} and nested objects are NOT supported (rejected with invalid_input). NOTE: applied AFTER semantic ranking, so it only filters the top relevance candidates -- a matching memory that scores low against the query can fall out. For an EXHAUSTIVE "give me everything tagged X", use amber_list_memories with its metadata_filter instead. WHEN (and only when) you pass metadata_filter, the response adds `filter_matched_total` (how many memories the filter matches in total) and `filter_truncated` -- if `filter_truncated` is true you are looking at a PARTIAL set and must NOT report it as complete; re-run via amber_list_memories to get all of them. NOTE: no value of n_results makes a filtered search exhaustive -- the filter is applied to a bounded relevance candidate pool, so amber_list_memories is the only exhaustive path.

Output Schema

NameRequiredDescriptionDefault
resultsYesMatches, best first. An empty array means nothing matched, which is an ordinary result rather than an error.
topics_resolvedNoOnly when `topics` was supplied: what each requested topic name actually matched among the topics that exist. Topic names are matched semantically, so a synonym resolves to a NEARBY topic ('hobbies' -> 'gaming'); check `matched` to see how your name was interpreted. Because the topic boost is a bounded tie-breaker, a correct resolution can still leave the ranking unchanged -- if you need topics to decide the order, pass an EXACT name from amber_list_topics.
filter_truncatedNoOnly when metadata_filter was supplied: true when filter_matched_total exceeds the number of results returned. Use `amber_list_memories` with the same metadata_filter to get the complete set.
filter_matched_totalNoOnly when metadata_filter was supplied: how many active memories match that filter IN TOTAL, regardless of how many ranked into this page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changedv1.1.6
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / keywords
      Added value: +{
      +  "description": "Optional EXACT lexical terms for the keyword (full-text) side of hybrid search -- the distinctive words the answer would contain: key nouns, product names, numbers, IDs, codes. E.g. for \"what car does the user drive?\" pass [\"car\", \"drive\"]. Pick them yourself and OMIT the subject's name (that's what `subjects` is for -- a name matches every fact about a person and only adds noise). If omitted, Amber extracts keywords heuristically. Semantic matching still runs on the query + query_variants; keywords only sharpen exact-term precision.",
      +  "items": {
      +    "maxLength": 100,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
    • changedInput schema / properties / metadata_filter / description
      Previous value: -"Optional metadata filter. Matches memories whose metadata contains every key-value pair given."New value: +"Optional EXACT-match metadata filter. Matches memories whose metadata contains every key-value pair given. Matching is TYPE-STRICT: metadata stored as the number 5 is matched by 5, NOT by \"5\". A null VALUE matches only memories that explicitly stored a null under that key -- a memory missing the key entirely does NOT match. Values must be SCALARS (string/number/boolean/null) -- operator objects like {\"$ne\": ...}/{\"$gte\": ...} and nested objects are NOT supported (rejected with invalid_input). NOTE: applied AFTER semantic ranking, so it only filters the top relevance candidates -- a matching memory that scores low against the query can fall out. For an EXHAUSTIVE \"give me everything tagged X\", use amber_list_memories with its metadata_filter instead. WHEN (and only when) you pass metadata_filter, the response adds `filter_matched_total` (how many memories the filter matches in total) and `filter_truncated` -- if `filter_truncated` is true you are looking at a PARTIAL set and must NOT report it as complete; re-run via amber_list_memories to get all of them. NOTE: no value of n_results makes a filtered search exhaustive -- the filter is applied to a bounded relevance candidate pool, so amber_list_memories is the only exhaustive path."
    • addedInput schema / properties / metadata_filter / propertyNames
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / near_date
      Added value: +{
      +  "description": "Optional ISO 8601 datetime to rank results by TEMPORAL PROXIMITY to -- memories whose own event time (event_start/event_end) sits closest to this rank higher. Use it when the query has a time focus that plain wording can't resolve: for \"where does the user work NOW?\" pass today's date so the current job outranks an older one; for \"what car did they drive back in 2019?\" pass \"2019-01-01\". Memories with no event date keep their relative order among themselves, though their absolute scores move slightly (measured: about 10% lower under any anchor, because anchoring renormalises the whole result set), and a far-in-time memory is never pushed BELOW an unboosted peer, though its absolute score drops 5-10% under renormalisation -- the ordering claim holds, the score claim did not, and this sentence used to make the stronger one. Pass it whenever the question genuinely has a time focus -- ESPECIALLY for relative-time wording (\"recently\", \"lately\", \"last week\"), because that wording carries no meaning the text search can match, so the anchor is the only thing that can find the right memory. Do NOT pass it for a time-agnostic question: dated memories can then surface above undated ones that answer it better. Omit when in doubt.",
      +  "type": "string"
      +}
    • addedInput schema / properties / near_date_end
      Added value: +{
      +  "description": "Optional ISO 8601 datetime. When set together with `near_date`, proximity is measured to the WINDOW [near_date, near_date_end] instead of a single instant (a memory whose event overlaps the window gets the full boost). Use for period queries like \"what happened during 2023?\" (near_date 2023-01-01, near_date_end 2023-12-31). REJECTED with invalid_input if `near_date` is not also given -- it marks the end of a window, so on its own it is a mistake rather than something to silently drop. Must be on or after near_date.",
      +  "type": "string"
      +}
    • addedInput schema / properties / query / maxLength
      Added value: +5000
    • addedInput schema / properties / query_variants
      Added value: +{
      +  "description": "Alternative phrasings of the SAME query that YOU generate -- synonyms, related terms, and any sub-questions -- exactly like the variants you attach when storing. Amber embeds and searches every one and fuses the results, so a memory worded differently than the user's phrasing still surfaces. Example: for \"what does the user eat?\" pass [\"the user's dietary preferences\", \"foods the user likes\", \"what food does the user avoid?\"]. Aim for 3-6; this replaces the automatic query expansion Amber used to do server-side.",
      +  "items": {
      +    "maxLength": 1000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "type": "array"
      +}
    • addedInput schema / properties / subjects
      Added value: +{
      +  "description": "REQUIRED. Who is this query about? An ARRAY -- usually ONE person, e.g. [\"patrick vane\"]. Routes ranking so the right person's facts surface. Use [\"self\"] (or [\"me\"]) when the query is about the USER (e.g. \"what foods is the user allergic to?\") -- lifts the user's OWN facts above facts about family or others. Use a person's FULL name (e.g. [\"patrick vane\"]) when the query is about them: subjects are matched by EXACT (case-insensitive) text, so it must match how they were stored -- a bare first name can miss them or hit a different person. Call amber_list_subjects to see the exact names already stored. Use [\"anyone\"] or [] for a general query with no personal focus (e.g. \"good pasta recipes\"). List several only when the query is genuinely about multiple people together. BOOSTS matching memories, never hard-filters -- other subjects still appear, lower down.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "type": "array"
      +}
    • changedInput schema / properties / topics / description
      Previous value: -"Optional topic filter. Pass category names like 'food', 'work', 'beliefs'. Matched semantically — 'beliefs' also finds memories categorized under related topics like 'opinions' or 'superstitions'."New value: +"Optional topic hint. Pass category names like 'food', 'work', 'beliefs'. What it actually does, in order: (1) each name is matched SEMANTICALLY against the topics that already exist and have live memories -- 'hobbies' resolves to 'gaming'; (2) the SEMANTIC half of the search is restricted to memories carrying one of the ~10 nearest topics, so on a store with many topics this genuinely narrows, while on a small store it may narrow nothing; (3) the keyword half is NOT restricted, so an off-topic memory can still appear via an exact word match; (4) closer topics get a bounded lift of at most 1.5x. That lift is a TIE-BREAKER and will NOT override relevance: a result scoring clearly better on the text still wins, so do not expect the on-topic memory to jump to #1. A synonym's edge over a near-neighbour topic is only a few percent; an EXACT existing name is far stronger. So if you need the topic to actually decide the order, call amber_list_topics and pass the exact name. The response reports `topics_resolved` -- what each name you passed matched -- so you can see how it was interpreted instead of guessing. A name matching nothing leaves the ranking unrestricted. Omit if unsure."
    • addedInput schema / properties / topics / maxItems
      Added value: +5
    • changedInput schema / required
      Previous value: -[
      -  "query"
      -]New value: +[
      +  "query",
      +  "subjects"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "filter_matched_total": {
      +      "description": "Only when metadata_filter was supplied: how many active memories match that filter IN TOTAL, regardless of how many ranked into this page.",
      +      "type": "number"
      +    },
      +    "filter_truncated": {
      +      "description": "Only when metadata_filter was supplied: true when filter_matched_total exceeds the number of results returned. Use `amber_list_memories` with the same metadata_filter to get the complete set.",
      +      "type": "boolean"
      +    },
      +    "results": {
      +      "description": "Matches, best first. An empty array means nothing matched, which is an ordinary result rather than an error.",
      +      "items": {
      +        "additionalProperties": {},
      +        "properties": {
      +          "content": {
      +            "description": "The fact itself, exactly as stored.",
      +            "type": "string"
      +          },
      +          "created_at": {
      +            "description": "ISO 8601 time the memory was stored. Not when the event happened: that is event_start.",
      +            "type": "string"
      +          },
      +          "deleted_at": {
      +            "description": "ISO 8601 time the memory was moved to the trash. Absent or empty for a live memory; present means amber_restore_memory can bring it back.",
      +            "type": "string"
      +          },
      +          "event_end": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "ISO 8601 datetime the fact's event ended, or null."
      +          },
      +          "event_start": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "ISO 8601 datetime the fact's event began, or null when the fact has no event date."
      +          },
      +          "memory_id": {
      +            "description": "The memory's id. Pass it to amber_get_memory, amber_update_memory, amber_delete_memory or amber_restore_memory.",
      +            "type": "string"
      +          },
      +          "metadata": {
      +            "additionalProperties": {},
      +            "description": "The caller's own exact-match filter values, as stored (a flat object). Absent or empty when none were set.",
      +            "propertyNames": {
      +              "type": "string"
      +            },
      +            "type": "object"
      +          },
      +          "score": {
      +            "description": "Relevance score. Higher = better match. Only meaningful for ranking results within the same query, not comparable across queries.",
      +            "type": "number"
      +          },
      +          "subject": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "Who this memory is about -- a named subject like \"patrick\" or \"patrick's father\", or null if not yet determined. Tells you whose fact each result is."
      +          },
      +          "subjects": {
      +            "description": "The same people as an ARRAY, which is the shape every tool ACCEPTS -- pass it straight back as `subjects` on a search. `subject` is the comma-joined rendering of the same value and matches nothing if passed as an argument; absent here means the memory has no attribution.",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "topics": {
      +            "description": "The topic names this memory is filed under (at most 3 for a new store).",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "truncated": {
      +            "description": "Present and true when `content` was shortened for this result. Call `amber_get_memory` with this `memory_id` for the full text.",
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "memory_id",
      +          "content"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "topics_resolved": {
      +      "description": "Only when `topics` was supplied: what each requested topic name actually matched among the topics that exist. Topic names are matched semantically, so a synonym resolves to a NEARBY topic ('hobbies' -> 'gaming'); check `matched` to see how your name was interpreted. Because the topic boost is a bounded tie-breaker, a correct resolution can still leave the ranking unchanged -- if you need topics to decide the order, pass an EXACT name from amber_list_topics.",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "matched": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "The closest EXISTING topic it resolved to, or null if the store has no topics yet."
      +          },
      +          "requested": {
      +            "description": "The topic name you passed.",
      +            "type": "string"
      +          },
      +          "similarity": {
      +            "description": "Cosine similarity of requested->matched (0-1, 3dp).",
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "requested",
      +          "matched",
      +          "similarity"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "results"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Goes far beyond the readOnly/idempotent/non-destructive annotations: discloses that results are ranked rather than filtered (with the anti-inference warning), 1000-char truncation, score non-comparability across queries, the drip-bucket rate limit, `filter_truncated` semantics, and topic lift bounds. The near_date paragraph, however, is self-referentially muddled ("the score claim did not, and this sentence used to make the stronger one"), leaving the agent unsure which claim currently holds — that undercuts otherwise excellent disclosure.

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

Conciseness2/5

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

Front-loaded reasonably at the top, but the body is bloated and repeats schema parameter prose nearly verbatim, then drifts into corrective meta-commentary about its own earlier wording. Sentences like "the ordering claim holds, the score claim did not, and this sentence used to make the stronger one" cost the reader without adding callable information.

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 9-parameter hybrid-search tool with nested `metadata_filter`, this covers the full decision surface: relevance judgement, absence inference, temporal ordering/timeline reading, error semantics, and how to get complete result sets. Nothing an agent needs in order to call it correctly is missing, and the output schema means return shape needn't be spelled out.

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

Parameters5/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real decision-level meaning: query must be natural language not keywords, `query_variants` replaces server-side expansion and should carry 3-6 phrasings, `keywords` must omit the subject name, and `subjects` uses exact case-insensitive matching with the `self`/`anyone` conventions. It also explains the topics-resolved/lift interaction that the schema alone does not make actionable.

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?

Opening sentence gives a specific verb+resource+scope: "Find active memories by semantic meaning." It then explicitly separates itself from siblings, naming `amber_list_memories` for chronological browsing and `amber_get_memory` for full content, so an agent can route correctly without opening another schema.

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 explicit when-to-use guidance (search-before-store check, relative-time queries need `near_date`), explicit when-not (don't pass `near_date` for time-agnostic questions, omit `topics` if unsure), and names the alternatives `amber_list_memories` (exhaustive filtered listing), `amber_list_topics`, and `amber_list_subjects`. It even specifies the diagnostic escape hatch per parameter.

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