basic-memory

Find

find

Read-only

Recursively list files by filename pattern or frontmatter metadata filters, scoped to a project path, to locate notes matching status, tags, ranges, or other predicates.

Instructions

Recursively list files by name glob or metadata predicates (e.g. "status=active"). Paths accept '/path'.

Input Schema

Name	Required	Description	Default
`meta`	No	Frontmatter metadata predicates, repeatable; every predicate must hold. One predicate per string, one predicate per key, at least one predicate; omit `meta` entirely for the directory listing. Forms: "status=active" equality "confidence>0.6" comparison: > >= < <= "priority in high,critical" any of the listed values "tags has security,oauth" array contains ALL listed values "score between 0.3,0.8" inclusive range "owner=null" key missing or explicitly null Values are JSON-scalar inferred ("true"/"false"/"null"/numbers become booleans/None/numbers); quote a token to force a literal string (e.g. 'status="true"'), including inside a list, where the quotes also protect a comma ('label in "a,b",c' matches "a,b" or "c") and a value that itself starts with an operator character ('range=">=5"'). Numbers must be finite, and null is only meaningful with "=" — the other operators compare against the value, and a comparison with null is never true. Keys accept dot-paths ("review.approved"); "note_type" aliases the frontmatter "type" key. String equality and "in" on either type spelling use normalized note-type matching ("LiteraryDevice" matches "literary_device"). Other metadata keys and operators retain their usual comparisons. Any other operator fails fast naming the supported set.
`name`	No	File-name glob to match, e.g. "*.md". None matches everything. Cannot combine with `meta` — scope with `path` instead.
`page`	No	Page number (1-indexed).
`path`	No	Directory to start from (default: project root). '<project>/path' routes into that project. With `meta`, scopes the search to this subtree (matched on a directory boundary, so "specs" never admits "specs-archive/").	/
`depth`	No	How many levels to recurse (1-10, default: 10). A non-default depth cannot combine with `meta` (the subtree scope is all-or-nothing).
`fields`	No	Frontmatter fields to return per hit (dot-paths allowed), e.g. ["title", "priority"]. Requires `meta`. A field missing on a hit renders as null — rows are never dropped. Requesting fields also narrows each row to the note's identity plus those values: the projection replaces the note body rather than riding alongside it.
`project`	No	Project name. Optional - qualified paths route themselves; unqualified paths refuse when several projects are addressable.
`page_size`	No	Nodes per page.
`project_id`	No	Project external_id (UUID); takes precedence over `project`.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.24.1Oct 23, 2026

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the recursion trait and the project-qualified path form, which are genuine behavioral facts, but says nothing about pagination behavior, result caps or how the two modes interact (the non-combinability of name and meta lives only in the schema).

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

Conciseness5/5

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

Two sentences with no filler: the primary capability leads, and the path-syntax caveat follows. Nothing is restated and every clause carries information an agent needs.

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

Completeness3/5

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

With an output schema, full schema coverage and safety annotations, most structural burden is carried elsewhere, so the short description is defensible. What remains missing is disambiguation in a very crowded sibling set (ls, list_directory, search, search_notes, grep) — without that, an agent can call it but may pick the wrong tool.

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 description coverage is 100%, so the schema already documents all nine parameters in depth; the baseline of 3 applies. The description adds only the '<project>/path' routing convention on top of that, which is a marginal increment rather than compensating for any gap.

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

Purpose4/5

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

States a specific verb and resource: recursively listing files, either by name glob or by metadata predicates, with the extra path-routing syntax. It is clearly distinguishable from the mutation siblings (edit_note, move_note), but it never contrasts itself with the closest read siblings (ls, list_directory, search_notes, grep), which is the only thing separating it from a 5.

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

Usage Guidelines3/5

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

Usage is implied by the two modes it names (glob for name matching, metadata predicates for frontmatter filtering) and by the note that paths accept '<project>/path'. There are no explicit when-to-use or when-not-to-use statements and no sibling is named as the alternative for, say, plain directory listing or full-text search, so the agent has to infer routing.

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