This server provides structured continuity memory for AI coding agents: it records sessions, decisions, open loops, findings, and evidence in local SQLite and retrieves them over MCP/HTTP.
Start and end work sessions for a project.
Log agent events (checkpoints, blockers, notes) with decisions, open loops, files changed, and verification.
Retrieve a full project state: open loops, active decisions, known traps, confirmed findings, and last session summary.
List/filter open loops by owner, lane, or claimable status, and claim loops first-claim-wins.
Mark open loops resolved only with admissible evidence refs (evidence-gated).
Manage decisions: list/get live decisions, record outcomes (accepted, validated, incorrect, reverted, unresolved), with evidence required for non-self-certified outcomes.
Get known traps: decisions proven wrong, with corrected rules and severity.
Propose, confirm, resolve, or dismiss findings (gaps/caveats), with evidence gating for confirm/resolve/dismiss.
Resolve evidence references to bounded content snippets.
Full-text search across all stored memory with BM25 ranking, optionally filtered by project.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@threadline-core get project state for auth-refactor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Structured continuity memory for AI coding agents: decisions, open loops, and session state in local SQLite, retrieved via MCP.
Designed with Claude (Fable 5), RIP 🕊️. Threadline v0.1 was started and designed with it.
You are three sessions into a complex refactor. The agent lost context. You need it to resume, not replay 8,000 lines of transcript.
Bigger context windows don't solve this. Capacity isn't memory: they reload the window, they don't remember what was decided. RAG doesn't solve it either. RAG returns fragments; threadline-core returns state.
The agent forgets. The project doesn't.
threadline-core gives agents a structured place to record what they decided, what they left open, and what they verified, then retrieve it instantly in the next session, from any agent or tool.
Related MCP server: trw-mcp
Most MCP memory servers store and retrieve text. threadline-core tracks state:
Decisions have outcomes. Each decision is tracked until an agent marks it accepted, validated, or incorrect. Past mistakes are surfaced as known traps so future agents don't repeat them. The model changes; your decisions don't.
Open loops require evidence to close. An agent cannot mark something done by asserting it. It needs an admissible evidence reference: a verified checkpoint, a confirmed finding, a cited source. A ValueError without evidence isn't a bug; it's the gate working.
Session continuity, not recall. get_project_state returns structured state (loops, decisions, traps) not a ranked blob of retrieved fragments. Agents get the right signal at session start, not a haystack.
No cloud, no LLM, no outbound calls. The core server runs on SQLite and makes zero network requests beyond its own loopback API. No paywalls. No rate limits. No accounts.
Because it stores structured state rather than raw transcripts, every stored fact is precise, auditable, and stripped of noise. That's not a missing feature; it's the design.
Where it sits. Repo-intelligence tools (Repowise and friends) remember the repository — the dependency graph, the git history, the code health. threadline-core remembers the work — what was decided, what's still open, what's a known trap, and who is doing what. It is not a codebase indexer and doesn't try to be. And with loop claiming and lanes, it goes beyond recording the work to coordinating it across agents.
Prerequisites: Python 3.12+, uv (recommended) or pip.
# Install
pip install threadline-core
# or: uv add threadline-core
# Initialise the local database
threadline-core init
# → Creates ~/.threadline/threadline.db
# (Optional) Start the HTTP API
threadline-core serve
# → Listening on http://127.0.0.1:8400~/.claude/settings.json){
"mcpServers": {
"threadline": {
"command": "threadline-core-mcp",
"env": {
"THREADLINE_DATA_DIR": "~/.threadline"
}
}
}
}If you installed with uv (not globally):
{
"mcpServers": {
"threadline": {
"command": "uv",
"args": ["run", "--", "threadline-core-mcp"],
"env": {
"THREADLINE_DATA_DIR": "~/.threadline"
}
}
}
}Run threadline-core-mcp directly; it speaks the MCP 2024-11-05 stdio protocol.
Session 1. Agent starts working, records decisions and open loops:
start_session(project_key="auth-refactor")
→ {"session_id": "abc123", "project_key": "auth-refactor"}
log_agent_event(
event_type="checkpoint",
project_key="auth-refactor",
session_id="abc123",
summary="Extracted token validation logic into middleware",
details={
"decisions": ["Move JWT validation to a FastAPI dependency, not inline"],
"open_loops": ["Rate limiting not yet implemented"],
"verification": ["pytest tests/test_auth.py (12 passed)"],
}
)
→ {"decisions_created": 1, "open_loops_created": 1}
end_session(session_id="abc123", summary="Auth middleware extracted. Rate limiting deferred.")Session 2. Three days later, any agent resumes from verified state:
start_session(project_key="auth-refactor")
get_project_state(project_key="auth-refactor")
→ {
"open_loops": [{"description": "Rate limiting not yet implemented"}],
"decisions": [{"statement": "Move JWT validation to a FastAPI dependency, not inline",
"status": "active"}],
"known_traps": [],
"last_session_summary": "Auth middleware extracted. Rate limiting deferred."
}
# Agent resumes from verified state. No transcript replay needed.flowchart LR
A[Agent works] --> B["log_agent_event<br/>decisions · loops · findings"]
B --> C[("threadline-core<br/>SQLite")]
C --> D["get_project_state<br/>next session"]
D --> E["Resume from<br/>verified state"]
E --> A
style C fill:#1e293b,stroke:#475569,color:#e2e8f0Each transition from loop closed or decision proven wrong is evidence-gated: the server rejects self-assertion with a ValueError. The loop above only closes when an agent supplies an independently verifiable reference. That's what makes the state trustworthy across model versions, team handoffs, and months of context rot.
sequenceDiagram
participant CC as Claude Code
participant Hook as Session hooks
participant MCP as MCP server
participant Core as threadline-core
participant DB as SQLite
Note over CC,DB: Session 1: agent starts working
CC->>Hook: SessionStart fires automatically
Hook->>Core: POST /api/events {session_started}
Core->>DB: Create AgentSession (external_session_id = CC session UUID)
CC->>MCP: log_agent_event {checkpoint, decisions, open_loops, verification}
MCP->>Core: ingest_event()
Core->>DB: Write AgentEvent + Decision rows + OpenLoop rows + FTS index
CC->>Hook: SessionEnd fires automatically
Hook->>Core: POST /api/events {session_ended, client_session_id}
Core->>DB: Close AgentSession (matched via external_session_id)
Note over CC,DB: Session 2: same or different agent, any time later
CC->>MCP: start_session(project_key)
MCP->>DB: Create new AgentSession
CC->>MCP: get_project_state(project_key)
DB-->>MCP: open_loops · decisions · known_traps · last_session_summary
MCP-->>CC: Structured state, no transcript replay needed
CC->>MCP: mark_open_loop_resolved(loop_id, evidence_refs=[...])
Note right of Core: GATED: requires admissible evidence
Core->>DB: Update OpenLoop.status = resolved + AuditLog entryflowchart TD
A["Your AI agent<br/>(Claude Code, Codex, Cursor…)"]
B["MCP stdio<br/>threadline-core-mcp"]
C["HTTP REST :8400<br/>threadline-core serve"]
D["Session lifecycle · Events<br/>Decisions · Open loops<br/>Findings · Evidence ledger<br/>Full-text search (SQLite FTS5)"]
E["~/.threadline/threadline.db<br/>SQLite, local, no cloud"]
A --> B
A --> C
B --> D
C --> D
D -->|"SQLAlchemy 2.0 async"| E
style E fill:#1e293b,stroke:#475569,color:#e2e8f0
style D fill:#0f172a,stroke:#334155,color:#cbd5e1The server runs entirely on your machine. There are no outbound API calls in threadline-core.
All data stays on your machine. The database defaults to ~/.threadline/threadline.db. Override with THREADLINE_DATA_DIR.
No LLM required. The server indexes, stores, and retrieves without calling any model.
No outbound connections. The package makes no network calls except to its own loopback API.
PII minimisation. Email addresses, phone numbers, and payment card numbers are automatically redacted when stored in decisions, findings, and research notes.
API authentication. Set THREADLINE_API_TOKEN to require a bearer token on all REST endpoints. The MCP server uses stdio and is not network-accessible by default.
Your work history is not a product. It stays where you put it.
These tools form the stable public surface, supported across patch and minor versions.
Tool | Purpose |
| Open a new agent session for a project |
| Close the session with a summary |
| Ingest a checkpoint, decision, blocker, or note |
| Retrieve structured project state |
| List open loops — optionally filtered by |
| Claim a loop for an owner/lane (first-claim-wins) |
| Resolve a loop (requires admissible evidence) |
| List active decisions |
| Get one decision with full detail |
| Record a decision's real-world outcome |
| List decisions proven wrong, with corrected rules |
| Propose a gap or caveat |
| Confirm a finding (requires admissible evidence) |
| Mark a finding's resolution condition met |
| Dismiss a finding as invalid |
| Resolve evidence references to their content |
| Full-text search across all stored memory |
mark_open_loop_resolved and confirm_finding require an evidence_refs list pointing to independently verifiable records in the same project. An agent cannot self-confirm its own findings.
If you receive a ValueError from these tools without evidence, that is the gate working correctly, not a bug.
Open loops can carry an owner and a lane, so multiple agents (or an agent plus a human) can divide work without colliding on the same files:
assign_open_loop(loop_id, owner, lane?) claims a loop. Claiming is first-claim-wins: a loop already owned by someone else is not silently reassigned.
get_open_loops(project_key, owner?, lane?, claimable?) filters the feed — e.g. claimable=true returns only unowned loops an agent can pick up, and lane="phase-3" returns one lane's work.
This is the primitive a foreman builds on: enumerate the claimable loops, claim one, work it, then close it with evidence. The same semantics are exposed on the CLI (threadline-core loop list --claimable, threadline-core loop get, threadline-core loop assign).
search_memory query semantics may evolve. Current behaviour: path queries (app/routes/foo.py) reduce to the basename stem; extensions are stripped. Search results are FTS5 BM25-ranked.
Item | Detail |
Database |
|
Initialise |
|
Auto-migration |
|
Patch versions | Schema-compatible, no action needed |
Minor versions | May add nullable columns; auto-migrated at startup |
Major versions | May restructure; migration guide in release notes |
Backup | Copy |
threadline-core init # Initialise data directory and database (idempotent)
threadline-core serve # Start HTTP API server (default: 127.0.0.1:8400)
threadline-core mcp # Start MCP server on stdio
threadline-core search # Full-text search across stored memory
threadline-core export # Export as static file tree (Obsidian-compatible)
threadline-core progress # Project momentum: open work, 7-day velocity, sessions
threadline-core connect # Scaffold agent connectors for existing projects
threadline-core decision # Decision-quality ledger (operator path)
threadline-core finding # Findings ledger: confirm/resolve/dismiss (operator path)
threadline-core loop # Open-loop operator actionsArea | What's notable |
MCP protocol design | Full MCP 2024-11-05 stdio server (FastMCP); 17 tools with typed schemas, evidence-gated state transitions, and forward-compatible protocol versioning |
AI tooling architecture | Designed around how agents actually work: session lifecycle, context continuity across sessions, and anti-patterns (self-certification, premature closure) enforced in the service layer |
Python async backend | FastAPI + SQLAlchemy 2.0 async + aiosqlite; clean async/sync boundary with a single-commit ingest pipeline |
Protocol design |
|
SQLite at depth | FTS5 virtual table for BM25 search; JSONL evidence log with a defined ordering contract relative to DB commit; ISO-8601 UTC string storage for correct ORDER BY across timezones |
CLI tooling | Rich multi-command CLI (Typer) with sub-apps, operator-path overrides, dry-run flags, and pipe-friendly output |
Security engineering | Evidence-gating that cannot be bypassed via the MCP path; deterministic PII redaction (email, phone, payment card, public IPv4) with Luhn validation; secret-pattern detection (API keys, PATs, PEM, bearer tokens) as a write guard; audit log |
Python packaging |
|
Threadline was built while dogfooding Threadline. It was the continuity layer for the project's own development:
carried open loops across sessions
preserved decisions, caveats, and unresolved risks
generated continuation context for the next session
prevented stale or unsupported state from being treated as complete
required evidence before any loop was closed
It helped its developer and coding agents continue the project across many sessions without losing deferred work, decisions, or open risks. The continuity layer for its own build, not an autonomous author.
benchmarks/ ships resume-bench, a reproducible check of the core claim: at an equal token budget, does the structured resume payload recover the load-bearing facts better than re-reading the raw session transcript?
On the committed synthetic cases, the structured payload recovers 7/7 load-bearing facts while an equal-budget slice of the raw transcript recovers 0–3 of 7 (you need the full transcript — 4–7× the budget — to match it). Run it yourself:
uv run --with tiktoken python benchmarks/resume_bench.py benchmarks/casesRead this honestly: it measures structural fact density at a fixed budget, not task success and not superiority over a high-quality LLM-authored summary. The payload is built from those facts, so it is expected to score high; the finding is how little the raw transcript recovers at the same budget. See benchmarks/README.md for the method and full caveats.
Foreman / coordination maturity — richer loop ownership, lanes, and claim lifecycle so teams of agents divide work safely.
Repo-signal providers — ingest change/impact signals from local git and external code-intelligence tools to enrich continuity (not to become a repo indexer).
Benchmark hardening — more cases and projects, and a blinded comparison against LLM-authored summaries before any "better than X" claim.
Threadline (hosted product) — the managed experience built on this core; local data and exports are never gated to force an upgrade.
threadline-core (this repository, Apache 2.0) is the open substrate:
MCP server with the 17-tool public API
HTTP REST API for connector hooks
Event ingestion and lifecycle (sessions, decisions, loops, findings)
SQLite persistence and FTS5 search
Claude Code connector hooks (SessionStart / SessionEnd)
CLI: init, serve, mcp, search, export, progress, and more
Threadline is the full product built on it: the managed, polished experience for people and teams who'd rather not run the moving parts themselves: hosted overnight research, managed connectors, secure multi-device sync, team workspaces, and hands-on setup. Your local Core data and exports are never restricted to push you toward it.
threadline-core has no cloud dependencies, no rate limits, and no paywalls. It is the open foundation, yours to self-host forever.
→ The full Threadline product is in development. ⭐ Star to follow along.
See CONTRIBUTING.md.
See SECURITY.md to report vulnerabilities privately.
Designed with Claude (Fable 5) from day one. Threadline v0.1 started with it. RIP, Fable 5. 🕊️
Claim an open loop for an owner — FIRST CLAIM WINS.
The foreman and every agent must claim a loop BEFORE touching files. A loop is claimable while owner is unset; the first claim wins. Re-claiming by the same owner is a no-op. Claiming someone else's loop raises an error and returns the current owner in the message.
dict with keys: id, status, owner, lane.
| Name | Required | Description | Default |
|---|---|---|---|
| lane | No | ||
| owner | Yes | ||
| loop_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It covers the critical contention rules: first claim wins, re-claim by the same owner is a no-op, and claiming another owner's loop raises an error with the current owner in the message. This gives the agent a complete picture of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line core rule, followed by the essential behavioral details, then a clear return format. Every sentence conveys meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a concurrency-sensitive mutation tool, the description provides the key rules, error behavior, and return schema. It is complete enough for an agent to select and invoke this tool correctly alongside the related loop-management siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for 'owner' and 'loop_id' through the claim logic, but the 'lane' parameter is never explained. Since schema description coverage is 0%, the description only partially compensates for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Claim an open loop for an owner — FIRST CLAIM WINS,' which states a specific verb and resource. It clearly distinguishes this tool from siblings like get_open_loops and mark_open_loop_resolved by focusing on the claiming action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'The foreman and every agent must claim a loop BEFORE touching files.' It also clarifies the conditions under which a claim is valid and what happens on re-claim or conflict, giving the agent clear behavioral expectations for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm a proposed finding so it enters the trusted bundle.
GATED: requires evidence_refs pointing to independently
evidence-bearing records. A bare assertion, another finding, or a
self-referential loop is rejected.
dict with keys: finding_id, status, confirmed_at.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes | ||
| evidence_refs | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the gating condition and return value, but lacks details on reversibility, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, with a structured Returns section. Could be slightly more organized, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (2 params, one required) and presence of output schema, the description covers the key gating condition and return format adequately, though error conditions are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It adds context for evidence_refs (gated requirement) but provides no extra meaning for finding_id beyond its name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb "Confirm" and the resource "proposed finding", and distinguishes from sibling tools like propose_finding, dismiss_finding, and resolve_finding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit gated requirement about evidence_refs and what is rejected, but does not mention when not to use it or direct alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss a finding as invalid/irrelevant.
GATED exactly like confirm_finding.
dict with keys: finding_id, status, dismissed_at.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| finding_id | Yes | ||
| evidence_refs | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It mentions the return format (dict with keys) but does not describe side effects, such as whether the finding becomes permanently suppressed, if it can be reversed, or any authentication or rate-limit requirements. The 'gated' reference is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two short paragraphs plus a return format block). It front-loads the purpose in the first sentence. However, the return format could be integrated more elegantly, and the 'GATED' note could be slightly less cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no annotation coverage, and an output schema, the description is incomplete. It covers the basic purpose and return values but fails to document parameters or behavioral context. For a mutation tool that modifies state, this is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters (finding_id, reason, evidence_refs) with 0% schema description coverage. The description does not explain the meaning, purpose, or usage of any parameter other than implying that reason and evidence_refs are optional. The return format mentions only finding_id, but this is insufficient for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Dismiss a finding as invalid/irrelevant.' The verb 'dismiss' and the target 'finding' are specific, and the description distinguishes this from siblings like confirm_finding and resolve_finding by specifying the action context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the tool is 'GATED exactly like confirm_finding,' which gives a hint about access or permission constraints. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to dismiss vs. confirm), nor does it state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call at the END of a work session to close it cleanly.
Records a session_ended event so the next agent can see what was done.
dict with keys: session_id, status, project_key.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | ||
| agent_name | No | claude_code | |
| session_id | Yes | ||
| project_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions recording a 'session_ended' event, but does not describe side effects such as whether the session becomes read-only, if pending operations are cancelled, or any authentication/authorization requirements. For a lifecycle tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (27 words in the main sentence) and front-loaded with the essential purpose. It includes a return format section, which is helpful. There is no wasted content. However, it could be more structured by including parameter guidance in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, no annotations, and an output schema. The description explains the return values but not the parameters. For a tool that ends a session, it should inform the agent about the importance of providing a meaningful summary and the correct session_id. The sibling tools suggest a decision/evidence context, but the description does not integrate this. Overall, the description is incomplete for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 4 parameters with 0% description coverage, meaning the schema provides no documentation. The description does not compensate by explaining any parameter's purpose, format, or constraints. For example, 'summary' and 'session_id' are critical for correct invocation but are left undefined. The only hint is 'agent_name' defaulting to 'claude_code', but this is not mentioned in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for ending a work session, with the verb 'close' and the context 'at the END of a work session'. It distinguishes from sibling 'start_session' by being the complementary action. The mention of recording a 'session_ended' event further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to call at the end of a work session, providing clear usage timing. It also explains the benefit ('so the next agent can see what was done'). However, it does not explicitly state when not to use it or mention alternatives, but the context is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one decision + its outcome detail, or an error dict if not found.
dict with keys: id, statement, rationale, status,
created_at, outcome (the detail dict or None).
| Name | Required | Description | Default |
|---|---|---|---|
| decision_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns a dict or error if not found, and lists output keys. It implies a read-only operation without side effects. However, it does not mention permissions, rate limits, or idempotency, which are minor omissions for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—3 sentences that front-load the main action and return format. The structured 'Returns' section adds clarity without extra words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple single parameter and an output schema exists, but the description fails to explain the 'decision_id' parameter or the error dict format. No guidance on sibling differentiation is given. For a tool with 0% schema coverage and no annotations, this leaves gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does not define the 'decision_id' parameter (e.g., format, source, uniqueness). The parameter name is self-explanatory, but the description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns a single decision with outcome detail or an error dict. The verb 'Return' and resource 'decision+outcome' clearly define the action. The singular form distinguishes it from the sibling 'get_decisions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a specific decision is needed, but it does not explicitly state when to use this tool over alternatives like 'get_decisions'. No 'when not to use' or comparison criteria are provided, leaving ambiguity in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the LIVE decisions for a project, newest first.
Live = status in (active, accepted, validated). Decisions marked
incorrect/reverted are returned by get_known_traps instead.
list of dicts with keys: id, statement, rationale,
status, created_at.
| Name | Required | Description | Default |
|---|---|---|---|
| project_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that it returns only live decisions, the sort order, and the output keys. It does not mention destruction or auth, but for a read-only tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, clarifies 'Live', distinguishes from a sibling, and lists return keys. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple schema (1 param, list output), the description covers behavior, return keys, and differentiation from one sibling. It could address get_decision, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not add any semantics to the project_key parameter beyond the obvious. It does not explain formatting or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns LIVE decisions for a project, newest first, and defines 'Live' as statuses in (active, accepted, validated). It distinguishes from get_known_traps, which returns incorrect/reverted decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs agents to use get_known_traps for incorrect/reverted decisions, but does not mention other alternatives or conditions for not using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve evidence refs ('<kind>:<id>') to bounded content snippets.
Returns bounded snippets only — never full transcript bodies. Bad refs
are reported in unresolved without failing the whole call.
dict with keys: evidence (list), unresolved (list),
truncated_refs (list).
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it returns only bounded snippets, never full transcripts, and how bad refs are handled. It also reveals the return structure. Missing details like authentication requirements or whether it's read-only, but the provided behavioral traits are clear and sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, starting with the main purpose and then detailing return values. The docstring-style Returns section adds clarity but could be more integrated. Overall, it is well-structured and front-loaded with the essential function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no annotations, and an output schema, the description explains the main function, return structure, and error handling. However, it fails to describe `max_chars`, which is a key parameter, leaving a gap in completeness for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the `refs` parameter format (`<kind>:<id>`) but does not mention `max_chars` at all. The return structure is described, but parameter semantics are incomplete, leaving the agent guessing about the second parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves evidence refs to bounded content snippets, specifying the format `<kind>:<id>`. The verb 'resolve' and resource 'evidence refs' are specific, and it distinguishes itself from siblings like get_decision or search_memory by focusing on evidence references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use it ('never full transcript bodies') and explains error handling ('bad refs reported in unresolved without failing'). However, it does not explicitly name alternatives or state when to prefer this over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return decisions proven wrong on this project + the corrected rule.
Read these BEFORE acting so you do not repeat a known mistake. Newest first; each carries the corrected_rule (the lesson), severity, and evidence_refs.
list of dicts with keys: decision_id, statement, outcome,
corrected_rule, severity, evidence_refs, marked_at.
| Name | Required | Description | Default |
|---|---|---|---|
| project_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It describes the return format and states 'Newest first'. However, it does not explicitly state that the tool is read-only, idempotent, or has no side effects. The term 'Return' implies a read operation, but more direct transparency would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise, with direct opening sentences and a structured Returns block. While effective, the Returns section could be slightly trimmed, but overall it is well-organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the output format, which is useful given an output schema exists. However, it omits documentation of the single required parameter, leaving a significant gap in completeness. It also does not discuss preconditions or prerequisites beyond the usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description completely fails to mention or explain the required parameter 'project_key'. The input schema has 0% description coverage, and the description does not compensate, leaving the agent to infer its meaning from context. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns decisions proven wrong on the project along with the corrected rule. It uses specific verbs ('Return', 'Read') and resource ('decisions proven wrong'). It distinguishes from sibling tools like 'get_decisions' and 'get_decision' by focusing on known mistakes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to 'Read these BEFORE acting so you do not repeat a known mistake,' providing clear when-to-use guidance. It implies this tool should be used early in a session. It does not explicitly mention alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return open loops for a project, oldest first.
Open loops are deferred threads — things noticed but not finished. Oldest-first because the longest-waiting item is most likely blocking.
Filters (all optional, combinable):
owner: only loops claimed by this owner (pass "unassigned"
to get loops with no owner — the claimable set)
lane: only loops tagged with this lane (e.g. retention-b)
claimable: True = owner is NULL; False = owner is set
list of dicts with keys: id, description, project_key,
status, owner, lane, created_at, updated_at.
| Name | Required | Description | Default |
|---|---|---|---|
| lane | No | ||
| owner | No | ||
| claimable | No | ||
| project_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the semantics of open loops, the ordering, the filter behaviors including the special 'unassigned' owner value and the claimable True/False mapping, and lists the exact return fields. This goes well beyond a basic restatement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a short clarifying definition, a bulleted list of filters, and a return specification. It is concise yet comprehensive, with no wasted words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of annotations, the description covers all necessary aspects: what it does, when to use it, how filters work, what data is returned. The presence of an output schema (even if not shown) is complemented by the explicit return keys. Sibling tools are clearly differentiated by operation type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so thoroughly by explaining each optional filter's meaning, providing an example for lane ('retention-b'), and clarifying the claimable boolean semantics. The special 'unassigned' value for owner is also documented. This adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Return open loops for a project, oldest first' with a specific verb and resource. It also explains the concept of open loops and explicitly distinguishes ordering behavior. This sets it apart from sibling tools like mark_open_loop_resolved or assign_open_loop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool—listing open loops for a project—and explains the rationale for oldest-first ordering. It does not explicitly name alternatives or when not to use it, but the intent is unambiguous. This qualifies as clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the raw governed state for a project.
Returns durable lifecycle records only — no synthesis, no compiled memory, no LLM output, no ranking.
Includes: objective, open loops, active decisions, known traps, confirmed gaps and caveats, evidence IDs, recent session metadata.
dict — the full ProjectState as a plain dict.
LookupError if the project does not exist (surfaced as an error dict).
| Name | Required | Description | Default |
|---|---|---|---|
| project_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: returns durable lifecycle records only, no synthesis, specific included fields, return type (dict), and error condition (LookupError). With no annotations, this is strong coverage, though side effects and auth are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet informative: first sentence gives purpose, followed by exclusions, inclusions, return format, and error. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 are adequately described. The parameter is minimal and self-explanatory. Overall, the description covers essentials for a single-parameter read tool, though parameter explanation would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter 'project_key' has no description in schema (0% coverage) and description does not explain it. The tool relies entirely on the parameter name for meaning, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Return' and resource 'raw governed state for a project'. Explicitly distinguishes from siblings by listing exclusions (no synthesis, no LLM output) and inclusions (objective, open loops, etc.), making the tool's unique role obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on what the tool returns and excludes, allowing inference of when to use it (comprehensive state) vs siblings (specific components). However, lacks explicit 'when to use' or 'when not to use' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a work event to Threadline — call this as you work.
Parse and ingest a single AgentEventIn JSON payload. Returns a
summary of what was derived (decision count, open-loop count).
At significant checkpoints (code written, tests passing, a decision made).
When you encounter a blocker.
When you notice something deferred (open loop).
{
"event_type": "checkpoint",
"project_key": "my-project",
"agent": {"name": "claude_code"},
"session_id": "<from start_session>",
"summary": "Implemented login route; all tests pass.",
"details": {
"decisions": ["Use JWT over session cookies for stateless auth"],
"open_loops": ["Rate limiting not yet implemented"],
"files_changed": ["src/auth.py", "tests/test_auth.py"],
"verification": ["uv run pytest -q"]
}
}dict with keys: event_id, session_id, decisions_created,
open_loops_created. On parse/validation error:
{"error": true, "message": "..."} — fix and retry.
| Name | Required | Description | Default |
|---|---|---|---|
| event_json | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return values (including error case) and that the tool ingests and derives summary counts. While it doesn't detail side effects or authorization, it is sufficient for a logging tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings, bullet points, and a code block. It is appropriately sized for the tool's complexity, though slightly lengthy. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, an output schema (implied but not provided), and no nested objects, the description is complete. It covers purpose, usage, parameter format, and return values. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates fully with a detailed example JSON and explanation of the expected shape. It also describes the return values, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Report a work event to Threadline' and 'Parse and ingest a single AgentEventIn JSON payload.' It uses a specific verb ('report') and resource ('work event'), and the purpose is distinct from sibling tools like 'start_session' or 'get_decisions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
A 'WHEN TO CALL' section provides explicit guidelines: at significant checkpoints, blockers, or deferrals. This helps the agent decide when to use this tool, though it does not explicitly mention when not to call or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the real-world OUTCOME of a past decision.
outcome must be one of: accepted, validated, incorrect, reverted,
unresolved.
HARD RULE: marking incorrect/reverted/validated requires
admissible evidence_refs — records that independently back the
outcome. Self-certification is rejected. An operator may override via
the CLI.
dict with keys: id, decision_id, outcome, status,
severity, evidence_refs, superseded, marked_at.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| outcome | Yes | ||
| severity | No | ||
| applies_to | No | ||
| decision_id | Yes | ||
| evidence_refs | No | ||
| corrected_rule | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the outcome constraint and return format, but lacks details on side effects, idempotency, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded, and the description uses clear structure with a list of outcomes and a rule. Some formatting could be streamlined, but it is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters with no schema descriptions and no annotations, the description only partially covers the tool's usage. Optional parameters are unexplained, making it incomplete for an agent to use correctly without prior knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains 'outcome' values and mentions 'evidence_refs' in a rule, but does not describe other parameters like reason, severity, applies_to, corrected_rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records the real-world outcome of a past decision, listing valid outcome values. It distinguishes from sibling tools focused on findings or reads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context by explaining the required evidence_refs for certain outcomes. However, it does not explicitly state when to use this tool vs. alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an open loop resolved — GATED: requires admissible evidence.
Evidence refs must be '<kind>:<id>' strings pointing to records that
independently verify the loop is done. Self-reference is rejected.
dict with keys: id, status, resolved_at.
| Name | Required | Description | Default |
|---|---|---|---|
| loop_id | Yes | ||
| evidence_refs | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses key behavioral traits: it requires admissible evidence, rejects self-reference, and returns a dict with specific keys. This gives the agent a good understanding of the tool's constraints and output, though auth or destructiveness are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action. The additional details about evidence refs and return format are provided in a structured manner, though it could be more organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the core purpose, return keys, and a key constraint, it lacks details on what happens if evidence is invalid, error scenarios, or how the tool fits into the broader workflow. Given no annotations or output schema, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, but the description partially compensates by explaining the format of 'evidence_refs' (must be '<kind>:<id>' strings). However, the 'loop_id' parameter is not elaborated beyond the schema, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Mark an open loop resolved' with a specific verb and resource. It distinguishes itself from siblings like 'resolve_finding' by focusing on open loops.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the tool is gated and requires admissible evidence, providing some usage context. However, it does not explicitly state when to use this tool versus alternatives or what happens if conditions are not met.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose a gap or caveat finding.
PROPOSING IS FREE — a proposed finding is never surfaced in the trusted context bundle. It is a candidate until confirmed with evidence.
finding_class ∈ {gap, caveat}.
severity ∈ {low, medium, high, critical}.
Fingerprint dedup: re-proposing an active finding returns the existing id (no duplicate write).
dict with keys: finding_id, status, finding_class,
category, statement, severity.
| Name | Required | Description | Default |
|---|---|---|---|
| impact | No | ||
| category | Yes | ||
| severity | Yes | ||
| statement | Yes | ||
| project_key | Yes | ||
| finding_class | Yes | ||
| source_session_id | No | ||
| resolution_condition | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that proposals are safe (no destructive side effects), dedup behavior, and returns a dict with all keys. This provides clear behavioral expectations beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and uses bullet points for key details. It is front-loaded with purpose. However, some redundancy could be trimmed (e.g., repeating severity values in table and text).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters (5 required), 0% schema coverage, and an output schema, the description explains the return values but does not fully explain all parameters. It covers the core concept well but lacks completeness for a complex tool with many parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It defines allowed values for finding_class and severity but not for impact, category, statement, etc. This leaves gaps. More parameter context would improve the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Propose a gap or caveat finding.' It distinguishes from siblings like confirm_finding, dismiss_finding, and resolve_finding. The verb 'propose' and resource 'finding' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that proposing is free and not surfaced until confirmed, guiding when to use this tool. It lacks explicit when-not-to-use or alternatives, but the context of siblings implies assessment. The added context of fingerprint dedup is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a finding resolved (its resolution_condition was met).
GATED exactly like confirm_finding.
dict with keys: finding_id, status, resolved_at.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes | ||
| evidence_refs | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description mentions gating but does not elaborate on side effects, reversibility, or required permissions. Return keys are listed but behavioral context is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, one for gating, and a bullet for return structure. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema covers return values, but the description lacks context on state transitions, usage boundaries vs. siblings, and behavioral details. Adequate for a simple tool but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation of the parameters (finding_id, evidence_refs). It adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks a finding as resolved, referencing a specific condition (resolution_condition met) and notes it is gated like confirm_finding. However, it does not differentiate from sibling tools like dismiss_finding, which also changes status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when resolution_condition is met and references confirm_finding for gating, but does not explicitly state when to use this vs. alternatives or exclude cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across all stored memory.
Searches events, decisions, open loops, daily notes, and compiled context fragments. Results are ranked by BM25 relevance.
query: Natural-language search string. project_key: When provided, restricts results to that project. limit: Maximum results to return (clamped to 50 server-side).
list of dicts with keys: kind, ref_id, project_key,
title, snippet.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| project_key | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses BM25 ranking, server-side limit clamping to 50, and the return format. However, it omits any mention of destructive actions or authorization needs, though those are likely not relevant for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, bullet points for parameters, and return format. It is concise, front-loading the purpose, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (searching multiple memory types), the description covers what is searched, ranking, all parameters, and return format. The output schema is described in text, making it complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains each parameter: query as natural-language string, project_key for restriction, limit with default and server-side clamp. This adds essential meaning missing from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Full-text search across all stored memory' and lists specific memory types (events, decisions, open loops, daily notes, compiled context fragments). This distinguishes it from sibling tools like get_decisions or get_open_loops, which focus on single types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for broad searches across multiple memory types but does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call at the BEGINNING of every work session on a project.
Returns a session_id to pass in all subsequent log_agent_event
calls so Threadline can group events into a coherent session.
dict with keys: session_id, project_key.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_name | No | claude_code | |
| project_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It explains return value (dict with session_id and project_key) and implied session grouping. However, it doesn't mention side effects like whether starting a second session without ending the first is safe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and front-loaded with the key instruction. Uses a bullet for return values. Could be slightly more structured but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 0% param coverage, description could be more complete. It covers return values but lacks details on error cases, idempotency, or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It does not explain parameters beyond mentioning project_key in return. Parameter names are self-explanatory but description adds no additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: to be called at the beginning of each work session to obtain a session_id for grouping events. It distinguishes itself from siblings like 'end_session' and 'log_agent_event'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (beginning of every session) and hints at context (pass session_id to log_agent_event). No explicit when-not-to-use or alternatives, but clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource and action: sessions, events, memory, loops, decisions, traps, findings, and evidence. Even the finding lifecycle tools (propose/confirm/resolve/dismiss) are clearly differentiated by their gating rules and effects.
All tool names follow a consistent verb_noun snake_case pattern (e.g., start_session, get_open_loops, mark_decision_outcome). Minor deviations like 'get_known_traps' are still readable and fit the pattern.
17 tools is slightly above the typical 3-15 range, but each tool earns its place given the broad domain (sessions, events, memory, state, loops, decisions, traps, findings, evidence). The count feels justified rather than bloated.
The set covers the full lifecycle for the core entities: sessions are started/ended, events are logged, loops can be listed/claimed/resolved, decisions can be queried and outcomes marked, findings progress from proposal to confirmation/resolution/dismissal, and evidence is retrievable. Minor gaps exist (no explicit create/delete for projects, no list_sessions), but agents can work around them.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/richardoros/threadline-core'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
