Datacron

Overview Schema Source Related Servers Discussions Admin

List notes

list_notes

Read-only

Discover Datacron vault structure before deeper reads: retrieve paginated notes, optionally scoped by folder, tags, or frontmatter, with ULID, title, tags, aliases, and timestamps.

Instructions

Use this to discover vault structure before deeper reads. Return an offset/limit paginated list of notes in the vault, optionally scoped to a subfolder and/or filtered by tags or top-level frontmatter (for example, frontmatter={'confidence': 'needs_verification'}). Each entry includes the stable ULID, title, tags, aliases, and timestamps.

Input Schema

Name	Required	Description	Default
`tags`	No
`limit`	No
`folder`	No
`offset`	No
`frontmatter`	No

Output Schema

Name	Required	Description	Default
`notes`	Yes
`total`	Yes
`offset`	Yes
`returned`	Yes
`truncated`	Yes
`next_offset`	Yes
`limit_applied`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.1.18Oct 18, 2026

addedOutput schema / $defs / NoteSummaryOutput / properties / metadata_truncated

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "title": "Metadata Truncated"
+}

addedOutput schema / $defs / NoteSummaryOutput / properties / source_mount
```
Added value: +{
+  "title": "Source Mount",
+  "type": "string"
+}
```

changedOutput schema / $defs / NoteSummaryOutput / properties / source_vault / enum

Previous value: -[
-  "docs",
-  "memory"
-]New value: +[
+  "docs",
+  "memory",
+  "extra"
+]

Changed3 schema fields changedv0.1.17Oct 17, 2026

addedOutput schema / $defs / NoteSummaryOutput / properties / source_vault

Added value: +{
+  "enum": [
+    "docs",
+    "memory"
+  ],
+  "title": "Source Vault",
+  "type": "string"
+}

addedOutput schema / $defs / NoteSummaryOutput / properties / writable
```
Added value: +{
+  "title": "Writable",
+  "type": "boolean"
+}
```

addedOutput schema / description

Added value: +"Successful ``list_notes`` payload."

First observedv0.1.0Jul 31, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description still adds real behavior: offset/limit pagination and the stable ULID identity of entries. It does not mention sort order or total counts, which matters for a paging tool.

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?

Three tight sentences, front-loaded with the discovery use case before mechanics. Minor overlap between 'optionally scoped to a subfolder and/or filtered by tags or top-level frontmatter' and the parameter list, but no padding.

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

Completeness4/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 documented, yet the description still summarizes entry fields, and it covers filtering and paging. It is essentially complete; only pagination ordering/total-count behavior is absent.

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 description coverage is 0%, so the description must carry the parameters, and it does: it explains folder scoping, tag filtering, frontmatter matching with a concrete example, and offset/limit paging. The limit default of 20 and the tags AND/OR semantics are left unstated, keeping it out of 5 territory.

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 ('Return ... list of notes in the vault') plus the scope mechanism (subfolder, tags, frontmatter). The opening line positions it relative to deeper reads, which distinguishes it from get_note/search_text siblings.

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

Usage Guidelines4/5

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

'Use this to discover vault structure before deeper reads' gives a clear when-to-use context and implies the alternative (targeted reads). It does not name search_text/search_regex explicitly or state when-not to use this listing, so it stops short of a 5.

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