Casefile

Overview Schema Source Related Servers Discussions Admin

Add project entry

add_project_entry

File project-level decisions, findings, artifacts, or notes in a project case so they persist across tasks and can be referenced or superseded by later decisions.

Instructions

Files an entry in a project's case: a decision, finding, artifact or note that concerns the project rather than one of its tasks.

The entry number counts inside the project, and TRK#7 addresses the entry from refs of any task or project case. Like a task entry filed by add_entry, a project entry stays as filed. A task token files project entries as it files task entries.

A project decision is in force until a later decision names it in supersedes; no entry changes, and the status is computed on read. Withdrawing a decision with no replacement is a decision too, one that supersedes it.

An empty title, or a reference to a missing entry, task or project, returns entry_fields_invalid naming the offending fields.

Input Schema

TableJSON Schema

Name	Required	Description
`key`	Yes	Project key, case-insensitive. An unknown key is refused with `project_not_found`
`body`	No	Entry body in markdown, stored and returned as is. It holds what a successor needs to continue; file contents and long outputs stay outside it, represented by a pointer and the gist
`refs`	No	References: task entries `TRK-42#12`, project entries `TRK#7`, tasks `TRK-7`, or a URL with a scheme (`https://…`, `file://…`). Anything else (`7`, `#7`, `docs/x.md`) is refused with `entry_fields_invalid`, as is an entry, task or project that does not exist; URLs are not checked
`type`	Yes	What the entry records about the project: - `decision` — a project decision: an option chosen among several, with the reason, that outlives a task and that other tasks are to follow; - `finding` — an established fact with its source; - `artifact` — a pointer to a result; - `note` — an entry that fits none of the types above. Summaries, questions, attempts, verdicts and remarks exist only in task cases
`title`	Yes	Entry title: its line in the case index of `get_project`. It states what happened, not how
`supersedes`	No	Numbers of earlier `decision` entries of this project that the new decision supersedes; accepted only with `decision`. A number outside the project's case or of another entry type is refused with `entry_fields_invalid`, a decision superseded already with `decision_not_in_force`, its successor in `details`
`idempotency_key`	No	Retry key chosen by the caller, e.g. a UUID. A repeat with the same key and the same arguments returns the first result and creates nothing; the same key with other arguments is refused with `idempotency_key_reused`. A key is bound to the caller's token and kept for 24 hours

Output Schema

TableJSON Schema

Name	Required	Description
`no`	Yes	Entry number in the project's case; with the key it forms `TRK#7`
`seq`	Yes	Journal sequence number, usable as `after` of `wait_journal`
`author`	Yes
`created_at`	Yes
`project_key`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.10.1Oct 6, 2026

addedInput schema / properties / supersedes

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "integer"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Numbers of earlier `decision` entries of this project that the new decision supersedes; accepted only with `decision`. A number outside the project's case or of another entry type is refused with `entry_fields_invalid`, a decision superseded already with `decision_not_in_force`, its successor in `details`",
+  "title": "Supersedes"
+}

changedInput schema / properties / type / description

Previous value: -"What the entry records about the project:\n- `decision` — an option chosen among several, with the reason;\n- `finding` — an established fact with its source;\n- `artifact` — a pointer to a result;\n- `note` — an entry that fits none of the types above.\nSummaries, questions, attempts, verdicts and remarks exist only in task cases"New value: +"What the entry records about the project:\n- `decision` — a project decision: an option chosen among several, with the reason, that outlives a task and that other tasks are to follow;\n- `finding` — an established fact with its source;\n- `artifact` — a pointer to a result;\n- `note` — an entry that fits none of the types above.\nSummaries, questions, attempts, verdicts and remarks exist only in task cases"

Changed1 schema field changedv0.8.1Sep 30, 2026

changedInput schema / properties / refs / description

Previous value: -"References: task entries `TRK-42#12`, project entries `TRK#7`, tasks `TRK-7`, URLs. An entry, task or project that does not exist is refused with `entry_fields_invalid`; URLs are not checked"New value: +"References: task entries `TRK-42#12`, project entries `TRK#7`, tasks `TRK-7`, or a URL with a scheme (`https://…`, `file://…`). Anything else (`7`, `#7`, `docs/x.md`) is refused with `entry_fields_invalid`, as is an entry, task or project that does not exist; URLs are not checked"

Addedv0.5.2Sep 25, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare non-read-only, non-destructive, non-idempotent, closed-world. The description goes beyond them by disclosing that entries stay as filed, that decisions remain in force until superseded, that status is computed on read, and that an idempotency key changes retry behavior. It does not discuss permissions or rate limits, so it stops short of the top mark.

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?

Purpose is front-loaded in the first sentence, and each subsequent paragraph covers a distinct concern (numbering/addressing, decision lifecycle, error behavior). The decision-lifecycle paragraph is slightly dense and could be tightened, but no sentence is filler.

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?

With an output schema present, return values need not be explained, and the description covers mutation semantics, idempotency, and failure modes (`entry_fields_invalid`, `project_not_found`, `decision_not_in_force`). It is nearly complete for a 7-parameter write tool, missing only permission/auth context.

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 coverage is 100%, so the baseline is 3. The description nonetheless adds real meaning: entry numbering counts inside the project, `TRK#7` addresses a project entry from `refs`, and `supersedes` must name in-force decisions of the same project. This exceeds what the schema descriptions alone convey.

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 (files) and resource (an entry in a project's case) and enumerates the entry types it accepts. It explicitly contrasts with the sibling `add_entry` by scoping itself to entries that concern the project rather than one of its tasks, so an agent can disambiguate without opening either schema.

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?

The description draws the project-vs-task boundary clearly ('concerns the project rather than one of its tasks') and repeatedly frames behavior relative to `add_entry`, which routes selection well. It stops short of an explicit 'use X when…, use Y when…' directive, so it is clear context rather than full routing guidance.

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