Skip to main content
Glama
delimit-ai

delimit

Official
by delimit-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Delimit Ledger List

delimit_ledger_list
Read-onlyIdempotent

Retrieve ledger items with filters for status, priority, tags, text, time window, or external link, plus sorting and pagination. Read-only queries for a venture's ledger.

Instructions

List ledger items with rich filters, sort, and pagination (LED-1145).

When to use: to query a venture's ledger with filters — by status, priority, tags, text, time window, or external link. When NOT to use: for a top-N summary (use delimit_ledger_context) or to fetch a single item (delimit_ledger_query).

Sibling contrast: delimit_ledger_context is the top-5 summary; delimit_ledger_query fetches one; this is the powerful list call.

Side effects: read-only. Calls ai.ledger_manager.list_items. Single-value status / priority are kept for back-compat. LED-5658: an unrecognized venture with no real project directory behind it stays harmless — it returns empty items rather than the shared canonical ledger — but the response carries additive sandboxed: true + warning fields so that isn't mistaken for "no matching items in the real ledger."

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNo"updated_at" (default), "created_at", or "priority".updated_at
textNoCase-insensitive substring match on title + description.
limitNoPage size. Default 20.
orderNo"asc" or "desc" (default).desc
cursorNoOpaque pagination token from prior next_cursor. Becomes invalid if filters change between calls.
fieldsNoResponse projection. "" / "*" = full; "slim" = subset; CSV = those fields only. Unknown names ERROR.
ledgerNo"ops", "strategy", or "both" (default).both
statusNoSingle-value status filter (back-compat).
ventureNoProject name/path. Empty = auto-detect.
priorityNoSingle-value priority filter (back-compat).
status_inNoComma-separated statuses (e.g. "open,blocked").
priority_inNoComma-separated priorities (e.g. "P0,P1").
created_afterNoISO-8601 timestamp lower bound on creation time. If omitted, no lower bound is applied.
updated_afterNoISO-8601 timestamp lower bound on last-update time. If omitted, no lower bound is applied.
created_beforeNoISO-8601 timestamp upper bound on creation time. If omitted, no upper bound is applied.
updated_beforeNoISO-8601 timestamp upper bound on last-update time. If omitted, no upper bound is applied.
tags_contains_allNoComma-separated tags; item must contain ALL.
linked_external_idNoSubstring match in description / tags / context (github URL, Linear id, Discord thread).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv4.7.9
    • addedInput schema / properties / created_after
      Added value: +{
+  "default": "",
+  "description": "ISO-8601 timestamp lower bound on creation time. If omitted, no lower bound is applied.",
+  "type": "string"
+}
    • addedInput schema / properties / created_before
      Added value: +{
+  "default": "",
+  "description": "ISO-8601 timestamp upper bound on creation time. If omitted, no upper bound is applied.",
+  "type": "string"
+}
    • addedInput schema / properties / cursor
      Added value: +{
+  "default": "",
+  "description": "Opaque pagination token from prior next_cursor. Becomes invalid if filters change between calls.",
+  "type": "string"
+}
    • addedInput schema / properties / fields
      Added value: +{
+  "default": "",
+  "description": "Response projection. \"\" / \"*\" = full; \"slim\" = subset; CSV = those fields only. Unknown names ERROR.",
+  "type": "string"
+}
    • changedInput schema / properties / ledger / description
      Previous value: -"\"ops\", \"strategy\", or \"both\"."New value: +"\"ops\", \"strategy\", or \"both\" (default)."
    • changedInput schema / properties / limit / description
      Previous value: -"Max items to return."New value: +"Page size. Default 20."
    • addedInput schema / properties / linked_external_id
      Added value: +{
+  "default": "",
+  "description": "Substring match in description / tags / context (github URL, Linear id, Discord thread).",
+  "type": "string"
+}
    • addedInput schema / properties / order
      Added value: +{
+  "default": "desc",
+  "description": "\"asc\" or \"desc\" (default).",
+  "type": "string"
+}
    • changedInput schema / properties / priority / description
      Previous value: -"Filter by priority - \"P0\", \"P1\", \"P2\", or empty for all."New value: +"Single-value priority filter (back-compat)."
    • addedInput schema / properties / priority_in
      Added value: +{
+  "default": "",
+  "description": "Comma-separated priorities (e.g. \"P0,P1\").",
+  "type": "string"
+}
    • addedInput schema / properties / sort
      Added value: +{
+  "default": "updated_at",
+  "description": "\"updated_at\" (default), \"created_at\", or \"priority\".",
+  "type": "string"
+}
    • changedInput schema / properties / status / description
      Previous value: -"Filter by status - \"open\", \"done\", \"in_progress\", or empty for all."New value: +"Single-value status filter (back-compat)."
    • addedInput schema / properties / status_in
      Added value: +{
+  "default": "",
+  "description": "Comma-separated statuses (e.g. \"open,blocked\").",
+  "type": "string"
+}
    • addedInput schema / properties / tags_contains_all
      Added value: +{
+  "default": "",
+  "description": "Comma-separated tags; item must contain ALL.",
+  "type": "string"
+}
    • addedInput schema / properties / text
      Added value: +{
+  "default": "",
+  "description": "Case-insensitive substring match on title + description.",
+  "type": "string"
+}
    • addedInput schema / properties / updated_after
      Added value: +{
+  "default": "",
+  "description": "ISO-8601 timestamp lower bound on last-update time. If omitted, no lower bound is applied.",
+  "type": "string"
+}
    • addedInput schema / properties / updated_before
      Added value: +{
+  "default": "",
+  "description": "ISO-8601 timestamp upper bound on last-update time. If omitted, no upper bound is applied.",
+  "type": "string"
+}
    • changedInput schema / properties / venture / description
      Previous value: -"Project name or path. Auto-detects if empty."New value: +"Project name/path. Empty = auto-detect."
  2. Changed5 schema fields changedv4.5.5
    • addedInput schema / properties / ledger / description
      Added value: +"\"ops\", \"strategy\", or \"both\"."
    • addedInput schema / properties / limit / description
      Added value: +"Max items to return."
    • addedInput schema / properties / priority / description
      Added value: +"Filter by priority - \"P0\", \"P1\", \"P2\", or empty for all."
    • addedInput schema / properties / status / description
      Added value: +"Filter by status - \"open\", \"done\", \"in_progress\", or empty for all."
    • addedInput schema / properties / venture / description
      Added value: +"Project name or path. Auto-detects if empty."
  3. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds meaningful behavior beyond them: it notes the internal call, documents back-compat for single-value status/priority, and explains the LED-5658 sandboxed behavior for unrecognized ventures including the additive `sandboxed: true` and `warning` fields. This prevents a false interpretation of empty results.

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?

The description is front-loaded with the core purpose, then moves through usage, exclusions, and edge-case behavior in a logical order. Each section earns its place, and even the detailed LED-5658 note is necessary to avoid misinterpreting empty returns.

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 an 18-parameter list tool with an output schema, the description covers purpose, filter capabilities, sibling routing, safety profile, and a subtle sandboxing edge case. Nothing an agent needs to select or invoke the tool correctly is missing, and the output schema handles return-value documentation.

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?

Input schema coverage is 100%, so the baseline is 3, but the description adds genuine value by grouping the 18 parameters into filter families (status, priority, tags, text, time window, external link) and clarifying back-compat semantics for `status` and `priority`. It also explains the important failure/sandboxing behavior of the `venture` parameter.

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?

The description opens with a specific verb and resource: "List ledger items with rich filters, sort, and pagination." It also names the exact sibling alternatives it is not, making the tool instantly distinguishable from delimit_ledger_context and delimit_ledger_query.

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?

It provides explicit "When to use" and "When NOT to use" guidance, naming delimit_ledger_context for top-N summaries and delimit_ledger_query for single items. The sibling contrast paragraph reinforces the decision without leaving inference to the agent.

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

Deploy Server

Other Tools