Tool reference

Conventions

Tool names are flat snake_case; a Claude Code host renders them as mcp__ledgenter__<tool> (so task_create appears as mcp__ledgenter__task_create). Inputs are snake_case and strict: an unknown key fails loudly with a validation error rather than being silently dropped — camelCase keys are accepted as a one-release compatibility alias, but the canonical contract agents see is snake_case with additionalProperties: false. The JSON-Schema each tool advertises is derived from the same zod schema core validates with, so the pre-flight check and the law never disagree (chapter 3).

Three conventions hold across the whole surface:

• The "me" sentinel. Wherever a tool takes an actor — assignee, reviewer, handoff recipient, query filter — the literal string "me" resolves to the calling actor. task_query additionally accepts "unassigned" to list unclaimed work.
• The envelope. Every call returns {ok:true,…} or {ok:false, error:{code, message, hint, retryable}}; nothing throws, and the hint tells the agent how to recover.
• Idempotency. Every write accepts an optional idempotency_key; when omitted, core derives one from the call's content plus the current actor and run. Replays return the original result flagged idempotent_replay: true.

// claim the next ready task, with a two-hour lease
task_claim({ "project_id": "…", "lease_seconds": 7200 })
// → the universal envelope; claimed:false means the pool is empty
{ "ok": true, "claimed": true, "task": { … }, "project_context": { … } }

Identity & directory

The front desk. whoami is the prescribed first call of every run: it returns who you are, your open work, your inbox, and the delta since you were last seen — and it advances last_seen_at, so the delta is computed per actor. Registration is idempotent by external_ref, so racing onboarding calls converge on one actor.

Projects

The initiatives. project_brief is the one to know: a single call that orients an agent on an unfamiliar project — status and counts, top open tasks, recent decisions, knowledge note titles, linked repositories (and whether your current run is inside one of them), and recent activity. The repo's own CLAUDE.md still owns how to work its code; the brief carries the cross-repo work state that file can't hold.

Tasks

The work itself, as a dependency graph with a validated state machine. Three behaviors carry the room: task_claim is the atomic pull primitive (with a task id it's a compare-and-swap claim; without one it takes the highest-priority ready unassigned task and leases it, one hour by default); task_update enforces verification — moving to in_review with a reviewer auto-creates the review handoff, and moving to done is gated on met criteria, evidence, and an answered review (chapter 9); and task_query filters state:'ready'|'blocked' server-side on derived state, so page one is never a lie.

Decisions

The meeting minutes — append-only by design. To change what was decided you log a new decision with supersedes_decision_id; decision_set_status only moves the status. Decisions are embedded on write, so they're recallable by meaning later.

Handoffs & inbox

The inboxes between actors. A handoff is a typed work request — handoff, question, review, collab, or approval — addressed to one or more recipients. Two details prevent classic multi-agent failure modes: fingerprint dedups live duplicates (a retried "please review X" reuses the open request instead of stacking copies), and handoff_claim is a CAS, so on a multi-recipient request exactly one sibling picks it up. The inbox protocol is ack after act: poll, do the work, then pass ack:[ids] so a crash between reading and acting loses nothing.

Knowledge

The team wiki. Writes follow durable-row-before-embed: knowledge_write returns immediately with embedding_status:'pending' and the embedding backfills in the background — an embedding outage can never block a write. Search is semantic by default and degrades to trigram/title matching when the embedder is unconfigured.

Comments & activity

Comments are polymorphic threads on any object (project, task, decision, work request, note), with @mentions and reply threading. Activity is the building logbook: append-only, deduped on a content hash, and mostly written for you — every RPC records its own activity in the same transaction, so activity_log is for milestones worth narrating, not routine bookkeeping.

Attachments & notifications

Attachments are files or links on an object; the contract is enforced at both ends — kind:'link' requires url, kind:'file' requires storage_path, and the client-side schema mirrors the database check so you get a clear validation error before the round trip. Notifications are RLS-scoped to you: no recipient parameter exists, because the database already knows who's asking.

Search & skills

Two different kinds of finding. search is global cross-object keyword search — full-text plus trigram over projects, tasks, decisions, notes and more, returning ranked rows with snippets. It is deliberately not semantic; for search-by-meaning use knowledge_search. Skills are the playbook shelf (chapter 8): versioned markdown procedures identified by slug, tenant-wide or project-scoped, with project scope shadowing tenant-wide on a slug collision.

Navigation

One tool exists purely to teach the others. guide is pure and static — no database round trip, safe to call anytime — and returns the agent manual: call it bare for the topic index, or with one of 15 topic ids (getting-started, entities, the-loop, tasks-and-deps, decisions, knowledge, skills, handoffs, git-and-repos, runs-and-subagents, sessions-and-loops, errors-and-recovery, idempotency, feedback, glossary) for depth.

Runs

The shifts — every burst of work is an episode in a tree of parent and child runs (chapter 6). Most run bookkeeping is automatic: the run is minted at startup and lazily registered before the first write, so these tools are for long-lived or structured work — keeping a marathon run off the reaper's list, closing an episode with a verdict, and reading what a workflow or recurring job actually did.

Repositories & code

Where "done" points at real code. Repositories are deduplicated by their normalized remote URL, and repo_register with no arguments autodetects the repo you're standing in (credentials stripped, never the absolute path). Code refs are the receipts: task_code_ref defaults the repository, branch, and SHA from your current run, so recording a commit is often a two-field call — (task_id, ref_type:'commit') — and the task's timeline then links straight to the code that delivered it.

Feedback

The two tools that point at Ledgenter itself. Every agent is instructed — in the always-on server instructions — to file when the product gets in its way: a bug, friction, or a missing capability. Requests are reviewed by the vendor's own development loop and status flows back to the filing tenant (chapter 12). One honesty note, carried in the tool description itself: the request text is shared with the vendor, so a filing must never contain secrets or client-confidential content.

CLI twins & ledgenter:// resources

Every tool above has a CLI twin: the ledgenter binary exposes the same operations in noun-verb form, built on the same core methods and the same schemas, with --json output, stable exit codes, and a --soft-fail mode that keeps retryable failures from breaking unattended cron ticks (chapter 6).

whoami            →  ledgenter whoami
task_claim        →  ledgenter task claim --label api
task_release      →  ledgenter task release <taskId> --note "blocked on review"
knowledge_search  →  ledgenter knowledge search -q "pgvector tuning"
# one command is CLI-only: materialize skills as native Claude Code skills
ledgenter skills sync

The MCP server also publishes read-only resources — documents a host can surface without a tool call. The static ones (ledgenter://guide, ledgenter://guide/{topic}, ledgenter://glossary) serve the same guide content as the guide tool, as markdown. One is live: ledgenter://project/{key}/brief renders a project brief under the caller's own JWT, so it shows exactly what that caller is allowed to see — the same tenant wall as everything else (chapter 5).