What can you do with this server?

Saga MCP is a local, SQLite-backed project tracker that gives coding agents persistent MCP tools to plan, track, and resume work across sessions. * Initialize the tracker and get a full project dashboard with a natural-language summary * Manage projects, epics, tasks, and subtasks with statuses, priorities, due dates, assignees, tags, and source-code references * Model task dependencies with automatic blocking/unblocking when dependencies are completed * Batch-create subtasks and batch-update tasks * Add threaded comments on tasks to leave context across sessions * Save, list, search, and delete typed notes (decisions, context, meetings, blockers, progress, etc.)- Create, list, apply, and delete reusable task templates with {variable} substitution * Search across projects, epics, tasks, and notes; view activity logs and session diffs * Export and import full projects as JSON for backup or migration * Operates entirely on a local .tracker.db file — no accounts, servers, or network calls

Saga MCP

by spranab

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

saga-mcp

npm npm downloads license IdeaCred

Your coding agent loses the plan between sessions. You come back tomorrow and it has no idea which of the five things you agreed on are done, which one is blocked on which, or why you rejected the second approach — because the plan lived in the context window, or in a TODO.md nobody updates.

saga-mcp gives the agent a real tracker instead: a SQLite file in your project holding projects, epics, tasks, subtasks, dependencies, comments, notes and decisions, exposed as 41 MCP tools. The agent writes to it as it works and reads it back when it returns. No accounts, no external service, no network calls — the database is a file you own.

Install

Add saga-mcp to your MCP client. The same block works for Claude Code (.mcp.json in your project), Claude Desktop (claude_desktop_config.json), and any other MCP client:

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": { "DB_PATH": "/absolute/path/to/your/project/.tracker.db" }
    }
  }
}

Restart the client. DB_PATH is the only required setting; the file and its schema are created on first use. Prefer a global install? npm install -g saga-mcp, then use saga-mcp as the command instead of npx.

Tested on Node 20, 22 and 24, on Linux, macOS and Windows.

Settings

Variable	Required	Description
`DB_PATH`	Yes	Path to the `.tracker.db` SQLite file. Created on first use.
`SAGA_PROJECT`	No	Scope every tool to one project, by id or name. Set this per repo when several repos share one database.
`SAGA_TOOLS`	No	`full` (default) lists all 41 tools. `core` lists only the 13 an ordinary tracking session needs, saving ~4,300 tokens per session. See token cost.

No API keys, no accounts, no external services.

Related MCP server: Project Tracker MCP Server

Your first session

You: "Set up tracking for the e-commerce API and plan out auth."

tracker_init({ project_name: "E-Commerce API" })
epic_create({ project_id: 1, name: "Authentication", priority: "high" })
task_create({ epic_id: 1, title: "Design auth schema", priority: "critical" })
task_create({ epic_id: 1, title: "Implement JWT auth", depends_on: [1] })
task_create({ epic_id: 1, title: "Add OAuth2 Google login", depends_on: [2] })

Tasks 2 and 3 come back blocked — their dependencies aren't done. Finish task 1 and task 2 unblocks itself.

Next session, you: "Where were we?"

tracker_next({})
  -> Work on #1 'Design auth schema' — critical priority, in the active epic
     'Authentication'. 2 other task(s) are blocked.

One recommendation with the reason. For the whole picture instead, tracker_dashboard({}) returns stats, epics, blocked and overdue tasks, recent activity and notes, with a summary on top.

And when you would rather look than ask, saga-web puts the same database in a browser:

What you get

The next thing to do — one recommendation with its reason, at a third the cost of the dashboard
Real sequencing — dependencies that auto-block and auto-unblock, a manual order the tools respect, and cycles refused rather than deadlocked
Guards against agent drift — a lockable description, and prerequisites enforced on write rather than merely reported
A web UI — saga-web serves the same database in a browser, read and write
Templates — reusable task sets with {variable} substitution, editable in place
Archiving and soft delete — get finished work out of the context you pay for, reversibly
Forgiving input — a smaller model sending an array as a JSON string doesn't silently collapse your batch into one record
One file, many projects — per-repo databases or one shared file
A full audit trail — every mutation logged with old and new values, and nothing an agent removes is unrecoverable
41 tools with MCP safety annotations on every one, and a tiered surface when you want a smaller context bill

Asking what to do next

tracker_dashboard hands an agent everything and leaves it to reason. tracker_next answers the question:

tracker_next()
  -> Work on #12 'Write the adapter' — already in progress, high priority, in the
     active epic 'Provider swap'. Next step: implement. Also overdue: #18 'Renew cert'.
     3 other task(s) are blocked.

One recommendation with the reason, the next unfinished subtask inside it, a couple of alternatives, and anything overdue or blocked. About a third the size of the dashboard.

The ordering rule worth knowing: continuing beats starting. A task already in progress outranks an untouched one that is overdue or higher priority, because abandoning work in flight just leaves two things unfinished — the overdue work is named in the summary instead. Blocked tasks are never recommended, archived epics and removed tasks are skipped, and subtask dependencies decide which step comes next inside the chosen task.

When nothing is actionable it says what to unblock rather than returning an empty answer:

Nothing is actionable: all 4 remaining task(s) are blocked.
Unblocking #7 'the keystone' would release 3 of them.

Ordering and dependencies

A deliberate order wins over a guess. task_list sorts by priority until someone arranges an epic, and from then on it follows the arrangement:

task_reorder({ epic_id: 2, ordered_ids: [8, 5, 6] })
task_list({ epic_id: 2 })                        // 8, 5, 6 — the plan, in order
task_list({ epic_id: 2, sort_by: "priority" })   // priority, if that is what you want

Priority is a reasonable guess about what matters; a sequence someone wrote down is not a guess. An agent handed a plan should start at the beginning of it, not at whichever step happens to be marked critical.

Nothing changes for epics nobody has arranged — those sort by priority exactly as before, and an explicit sort_by is always obeyed literally.

Anything omitted from ordered_ids keeps its relative position at the end. sort_order runs ascending — lower sorts first — and a task created after an arrangement has no place in it, so it lands at the end rather than the front. In the web UI you can drag tasks into place inside an epic.

Task dependencies auto-block and auto-unblock:

task_update({ id: 9, depends_on: [8] })   // 9 becomes blocked while 8 is open

Re-evaluation runs whenever a blocker's doneness changes in either direction, so reopening a finished blocker blocks its dependents again, and clearing the last dependency releases them. Circular dependencies are refused with the loop named, for tasks and subtasks alike — anything in a cycle would be blocked forever. The web UI shows a banner at the top of a blocked task naming what it waits on, with a picker to add or remove dependencies.

Keeping agents on the rails

Two guards for the ways an agent goes wrong on a long task.

A locked description. Agents sometimes rewrite a task's description to record progress, when they meant to add a comment — and the spec you agreed on is gone. Lock it and task_update refuses:

task_lock_description({ id: 12 })
task_update({ id: 12, description: "..." })
  -> Task 12's description is locked and was not changed. Record progress with
     comment_add instead, or unlock it in the web UI if the description is genuinely wrong.

Everything else about the task stays editable — the point is to protect the spec, not freeze the task. The lock cannot be cleared as a side effect of an ordinary task_update; it takes a deliberate task_lock_description call or the lock toggle in the web UI, and both are logged.

This is a guard against confusion, not an adversarial control: an agent that is told to unlock still can. It turns a silent overwrite into a visible, reversible decision.

Subtask order and dependencies. New subtasks are appended in order rather than all landing at position 0, subtask_reorder sets the order in one call (or drag them in the UI), and a subtask can wait on its siblings:

subtask_update({ id: 8, depends_on: [5, 6] })    // 8 waits for 5 and 6
subtask_update({ id: 4, blocks: [5, 6, 7, 8] })  // a bug that holds up the rest

Reads carry depends_on and blocked, and the block is enforced on write: starting or finishing a subtask whose prerequisites are unmet is refused, and so is completing a task whose checklist is still open.

subtask_update({ id: 8, status: "in_progress" })
  -> Subtask 8 cannot be started — it waits on #5 'write the parser' (todo).
     Finish those first, or pass force: true to override deliberately (the override is logged).

force: true is the way past, for when a person has decided the blocker no longer applies. It works on subtask_update, task_update and task_batch_update, and every override is written to the activity log naming what was skipped. The web UI asks for confirmation and then sends it.

The distinction that matters is between an agent quietly ignoring a blocker and someone choosing to override one. Dependencies stay within one task — a checklist item waiting on something under a different task is a task-level dependency, and task_update depends_on already models that.

Comments as a decision trail

comment_add({ task_id: 5, content: "Investigated root cause: CORS headers missing on preflight" })
comment_add({ task_id: 5, content: "Fixed by adding OPTIONS handler. Tested with curl." })
task_update({ id: 5, status: "done" })

Comments persist across sessions — next time an agent calls task_get(5), it sees the full thread.

If a comment turns out to be wrong, retract it without losing the trail:

comment_delete({ id: 12, reason: "Root cause was wrong — it was a proxy timeout", deleted_by: "pranab" })

The row stays in the database and in the activity log. comment_list and task_get skip it, comment_list({ task_id: 5, include_deleted: true }) shows it with its reason, and comment_restore({ id: 12 }) brings it back. Nothing an agent removes is unrecoverable.

Templates

A reusable set of tasks with {variable} placeholders, filled in when applied:

template_create({
  name: "feature_workflow",
  tasks: [
    { title: "Design {feature} API",       priority: "critical", estimated_hours: 2 },
    { title: "Implement {feature}",        priority: "high",     estimated_hours: 8 },
    { title: "Write tests for {feature}",  priority: "high",     estimated_hours: 4 }
  ]
})

template_apply({ template_id: 1, epic_id: 2, variables: { feature: "user auth" } })
// -> "Design user auth API", "Implement user auth", "Write tests for user auth"

Templates are editable in place, which matters because the id is what template_apply refers to — recreating one breaks anything holding it:

template_update({ id: 1, name: "Feature rollout" })                  // tasks untouched
template_update({ id: 1, tasks: [{ title: "Design {feature}" }] })   // name untouched
template_list({ include_tasks: true })                               // see what one creates

Task definitions are checked when written rather than when applied, so a bad priority or a missing title is refused up front instead of failing later against an epic you have already chosen. Templates live in the database as a whole, not inside one project.

The Templates tab shows what each one creates, and the {placeholders} it will ask for:

Getting old work out of the way

An epic list that is mostly finished work, and tasks an agent created that should have been subtasks, are context you pay for on every call.

epic_archive({ id: 4 })            // the epic and its tasks drop out of listings
task_delete({ id: 12, reason: "should have been a subtask" })

Archiving is deliberately not the cancelled status: cancelled means "we decided not to do this", while most of what you want to archive is completed. Archived epics and their tasks disappear from epic_list, tracker_dashboard, task_list and tracker_search — including the statistics, not just the lists — and come back with include_archived.

Nothing vanishes silently. The dashboard says what it left out:

Hidden: 2 archived epic(s) and 1 removed task(s) — pass include_archived to include them.

task_delete is the same soft delete comments have, restricted to tasks still in todo: anything further along has comments, time tracking and an activity log that removing it would strand, and a task other tasks depend on is refused outright so nothing is left blocked forever. The row is kept, task_restore brings it back, and tracker_export includes archived and removed rows because a backup that omits things is not a backup.

Forgiving input

Smaller models routinely send an array parameter as a string containing JSON. Every array-taking tool accepts that, so a batch does not silently collapse into one record:

subtask_create({ task_id: 3, titles: '["Write it","Test it"]' })   // 2 subtasks
subtask_create({ task_id: 3, titles: "- Write it\n- Test it" })    // 2 subtasks
task_batch_update({ ids: "[4,5]", status: "done" })                // both tasks
task_create({ epic_id: 1, title: "x", tags: "billing, urgent" })   // 2 tags

Coercion stops where intent becomes ambiguous. A comma inside a title is left alone — "Design the API, then implement it" is one subtask, not two — while a comma in a tag or an id list is a separator, because neither can contain one. Anything genuinely unusable is refused with a message naming what arrived and what was wanted, rather than a leaked ids.map is not a function.

One database, many projects

saga-mcp works either way: a .tracker.db per repo (portable, keeps unrelated work apart), or one shared database that every repo points at.

The shared setup needs one extra thing. projects is the top-level table, so a shared file holds several projects — but task_list, note_list, activity_log and tracker_search read across the whole file unless told otherwise. An agent in repo B would see repo A's tasks. Set SAGA_PROJECT per repo and each agent sees only its own:

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": {
        "DB_PATH": "/Users/you/saga/central.tracker.db",
        "SAGA_PROJECT": "Payments platform"
      }
    }
  }
}

SAGA_PROJECT takes a project id or a project name (case-insensitive), and fails on startup with the list of real projects if it matches neither. Every scoped tool also accepts an explicit project_id argument, which wins over the environment variable.

Setup	What to set	Result
One database per repo	`DB_PATH`	Nothing to scope — one project per file
Shared database, per-repo agents	`DB_PATH` + `SAGA_PROJECT`	Each agent sees only its project
Shared database, one agent over everything	`DB_PATH`	Tools read across all projects

With neither SAGA_PROJECT nor a project_id, tracker_dashboard falls back to the first project in the file and says so — the response carries other_projects and the summary explains that the project was a guess, rather than silently reporting on the wrong repo.

The web UI is unaffected either way: its project switcher lists every project in the database, and each tab is scoped to the selected one.

Web UI

Everything above is agent-facing. saga-web puts the same database in a browser — for the times when reviewing a spec an agent just wrote, or fixing one field by hand, is faster than another prompt.

npx -p saga-mcp saga-web ./.tracker.db --open

Or against a database you already point your MCP server at:

saga-web --db ~/saga/central.tracker.db --port 8080

Option	Default	Description
`--db <path>`	`$DB_PATH`	Database to open. A positional path works too.
`--port <n>`	first free from `4319`	Omit it and saga-web takes the first free port, so one instance per project just works. `--port N` binds exactly N and fails if taken; `--port 0` lets the OS choose. Also `SAGA_WEB_PORT`.
`--host <addr>`	`127.0.0.1`	Bind address. Local-only by default.
`--read-only`	off	Serve the UI with every editing control removed.
`--open`	off	Open the UI in your default browser.

Six tabs:

Overview — stats, per-epic progress, blocked and overdue tasks
Board — kanban across the five task statuses; drag a card to change its status

Epics — the full Epic → Task → Subtask tree, which is the fastest way to review a spec an agent just wrote. Blocked tasks carry a ⛔ naming what they wait on, finished ones are struck through, and tasks drag into order

Notes — decisions, context and blockers
Templates — every template with the tasks it creates and the {placeholders} it uses; edit the details, edit the task list, apply it to an epic, or delete it
Activity — the complete change history

And throughout:

Task drawer — edit any field, comment, remove or restore a comment, lock the description, drag subtasks into order, and set which subtasks wait on which. Each subtask has one control carrying its whole state (todo / in progress / done, or blocked), and the drawer resizes by dragging its edge

Markdown — descriptions, comments and notes render headings, tables, lists, code and links. Agent-written content is escaped before any markdown rule runs, so raw HTML can never reach the page, and only http/https/mailto links are followed
Project switcher — every project in the database, so one central .tracker.db covers all your repos; every tab, including Activity, is scoped to the selected project
Shareable, refreshable URLs — the open project, tab and task live in the address bar, so a browser refresh puts you back where you were and back/forward move between tasks. A ⟳ button in the task drawer re-reads that task without a page reload, for picking up what an agent just wrote

Writes from the UI call the same handlers the MCP tools do, so edits you make by hand are validated identically and land in the same activity log as the agent's — an agent calling tracker_dashboard after you fix something sees the fix and how it happened.

A few deliberate limits: it binds to 127.0.0.1 unless you ask otherwise, it has no authentication (don't put it on a shared network), and it will not create a database — point it at one your MCP server already uses. Separate .tracker.db files are not yet aggregated into one view; a single database with multiple projects is.

Token cost

The tool list is context every session pays before any work happens, and list responses are context it pays again on every call. Both are kept deliberately small:

Responses are compact JSON — no pretty-print indentation, which measured 20-27% of every response
task_list rows omit nulls and metadata, and truncate descriptions to 120 characters (call task_get for a task's full text) — 19-39% smaller depending on how long your descriptions run
activity_log omits null columns and the row id (no tool takes one) — about 27% smaller
tracker_search returns previews rather than whole records — about 47% smaller; follow up with task_get or note_list for the full text
SAGA_TOOLS=core drops the listed surface from ~7,200 tokens to ~2,900

note_list deliberately keeps full note content — it is the retrieval tool, not a preview.

Set SAGA_TOOLS=core when an agent only tracks work; leave it unset when you want templates, import/export, session diffs and the rest discoverable. Tools left off the list still work when called by name — core shrinks what is advertised, not what exists.

The core thirteen: tracker_init, tracker_next, tracker_dashboard, project_list, epic_create, epic_list, task_create, task_list, task_get, task_update, subtask_create, note_save, comment_add.

Every tool description is held to a byte budget in the test suite, so the surface cannot grow by accretion: adding a tool means trimming prose elsewhere or justifying the increase.

Tool reference

Getting started

Tool	Description	Annotations
`tracker_init`	Initialize tracker and create first project	`readOnly: false`, `idempotent: true`
`tracker_next`	What to work on next, with the reason and what is blocked	`readOnly: true`
`tracker_dashboard`	Full project overview with natural language summary	`readOnly: true`

Projects

Tool	Description	Annotations
`project_create`	Create a new project	`readOnly: false`
`project_list`	List projects with completion stats	`readOnly: true`
`project_update`	Update project (archive to soft-delete)	`readOnly: false`, `idempotent: true`

Epics

Tool	Description	Annotations
`epic_create`	Create an epic within a project	`readOnly: false`
`epic_list`	List epics with task counts	`readOnly: true`
`epic_update`	Update an epic	`readOnly: false`, `idempotent: true`
`epic_archive`	Archive/unarchive an epic, hiding it and its tasks from listings	`readOnly: false`, `idempotent: true`

Tasks

Tool	Description	Annotations
`task_create`	Create a task with optional dependencies	`readOnly: false`
`task_list`	List/filter tasks; follows a manual arrangement when one exists	`readOnly: true`
`task_get`	Get task with subtasks, notes, comments, and dependencies	`readOnly: true`
`task_update`	Update task (auto-logs, auto-blocks/unblocks)	`readOnly: false`, `idempotent: true`
`task_batch_update`	Update multiple tasks at once	`readOnly: false`, `idempotent: true`
`task_reorder`	Set the order of an epic's tasks	`readOnly: false`, `idempotent: true`
`task_lock_description`	Lock/unlock a description so agents can't rewrite it	`readOnly: false`, `idempotent: true`
`task_delete`	Remove a `todo` task (soft delete, restorable)	`readOnly: false`, `idempotent: true`
`task_restore`	Restore a removed task	`readOnly: false`, `idempotent: true`

Subtasks

Tool	Description	Annotations
`subtask_create`	Create subtask(s) — supports batch	`readOnly: false`
`subtask_update`	Update title/status/position; `depends_on` and `blocks` set ordering	`readOnly: false`, `idempotent: true`
`subtask_reorder`	Set the order of a task's subtasks in one call	`readOnly: false`, `idempotent: true`
`subtask_delete`	Delete subtask(s) — supports batch	`destructive: true`, `idempotent: true`

Comments

Tool	Description	Annotations
`comment_add`	Add a comment to a task (threaded discussion)	`readOnly: false`
`comment_list`	List comments on a task (removed ones hidden unless `include_deleted`)	`readOnly: true`
`comment_delete`	Remove a comment — soft delete, row kept for audit	`readOnly: false`, `idempotent: true`
`comment_restore`	Restore a removed comment	`readOnly: false`, `idempotent: true`

Templates

Tool	Description	Annotations
`template_create`	Create a reusable task template with `{variable}` placeholders	`readOnly: false`
`template_list`	List templates; `include_tasks` shows what each one creates	`readOnly: true`
`template_update`	Edit a template in place — name, description or tasks	`readOnly: false`, `idempotent: true`
`template_apply`	Apply template to create tasks with variable substitution	`readOnly: false`
`template_delete`	Delete a template	`destructive: true`, `idempotent: true`

Notes

Tool	Description	Annotations
`note_save`	Create or update a note (upsert)	`readOnly: false`
`note_list`	List notes with filters	`readOnly: true`
`note_search`	Full-text search across notes	`readOnly: true`
`note_delete`	Delete a note	`destructive: true`, `idempotent: true`

Search, history and transfer

Tool	Description	Annotations
`tracker_search`	Cross-entity search (projects, epics, tasks, notes)	`readOnly: true`
`activity_log`	View change history with filters	`readOnly: true`
`tracker_session_diff`	What changed since a timestamp — call at session start	`readOnly: true`
`tracker_export`	Export full project as nested JSON (includes dependencies and comments)	`readOnly: true`
`tracker_import`	Import project from JSON (matching export format)	`readOnly: false`

How it works

Everything lives in a single SQLite file. The schema is created on first use, and existing databases are migrated in place when you upgrade — there is no migration step to run.

Project
  └── Epic (feature/workstream)
        └── Task (unit of work)
              ├── Subtask (checklist item)
              ├── Comment (discussion thread)
              └── Dependencies (blocked by other tasks)

Note types

Notes replace scattered markdown files. Each note has a type:

Type	Use case
`general`	Free-form notes
`decision`	Architecture/design decisions
`context`	Conversation context for future sessions
`meeting`	Meeting notes
`technical`	Technical details, specs
`blocker`	Blockers and issues
`progress`	Progress updates
`release`	Release notes

Activity log

Every create, update and delete is recorded, with the old and new value:

{
  "summary": "Task 'Fix CORS issue' status: blocked -> done",
  "action": "status_changed",
  "entity_type": "task",
  "entity_id": 15,
  "field_name": "status",
  "old_value": "blocked",
  "new_value": "done",
  "created_at": "2026-02-21T18:30:00"
}

That log is what makes the soft deletes safe and the time tracking automatic — hours are computed from it rather than entered by hand.

Privacy

saga-mcp is a fully local, offline tool. It does not collect user data, send anything to external servers, require internet access after installation, or use analytics or telemetry of any kind.

All data is stored exclusively in the local SQLite file specified by DB_PATH. Uninstalling saga-mcp and deleting the .tracker.db file removes all traces.

Development

git clone https://github.com/spranab/saga-mcp.git
cd saga-mcp
npm install
npm run build
DB_PATH=./test.db npm start

# the web UI against the same database
node dist/web/index.js ./test.db --open

npm test     # 298 unit and integration tests, no network
npm run e2e  # release gate: packs a tarball, installs it, drives the real binaries

npm test runs against the built output. npm run e2e is the gate that matters before a release: it packs the tarball that would actually be published, installs it somewhere else, and drives both binaries over real stdio — 106 checks, including an upgrade from an older database.

Releasing

Publishing to npm is irreversible — a version number can never be reused — so it is the last step, and it is triggered by publishing a GitHub release, not by pushing a tag.

# 1. bump the version in package.json, manifest.json and server.json, then merge
# 2. tag it. Nothing is published yet.
git tag -a v1.16.0 -m "v1.16.0 — ..." && git push origin v1.16.0

# 3. verify the tagged build: this packs the tarball that would be published
#    and drives it end to end, including an upgrade from an older database.
npm run e2e

# 4. publish the release. This fires the publish workflow.
gh release create v1.16.0 --notes-file notes.md

The workflow re-runs the suite against the tagged commit, refuses a tag that does not match package.json, refuses a version already on npm, and sends a GitHub pre-release to the next dist-tag so it never becomes what npm install saga-mcp gives people. A failed publish can be retried against the same tag with gh workflow run "Publish to npm" -f tag=v1.16.0.

Support

Issues: https://github.com/spranab/saga-mcp/issues
Repository: https://github.com/spranab/saga-mcp

Bug reports that come with a reproduction are worth a great deal here — several of the sharper behaviours above exist because someone reported that the obvious thing was wrong.

Part of a set of agent infrastructure built by one person, meant to be used together:

yantrikdb-mcp — persistent cognitive memory for the same agent: what it learned, not what it planned.
brainstorm-mcp — multi-model debate before you commit a plan to the tracker.
swarmcode — real-time channel between Claude Code instances on different machines.
truenas-mcp — 278 TrueNAS SCALE actions behind one hierarchical tool.
mcpier — self-hosted MCP control plane that keeps API keys off your clients.

License

MIT

Available Tools

41 tools

activity_logA

Read-onlyIdempotent

View the activity log showing what changed and when. Useful for understanding recent progress or reviewing what happened since the last session.

ParametersJSON Schema

Name	Required	Description
`limit`	No
`since`	No	ISO 8601 datetime - show only activity after this time
`action`	No	Filter by action type
`entity_id`	No	Filter by specific entity
`project_id`	No	Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database.
`entity_type`	No	Filter by entity type

TDQS

A3.8/5.0

Behavior3/5

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered and the bar is lower. The description adds the content contract ('what changed and when') and a temporal framing, but does not disclose ordering, pagination, or whether deleted entities appear in the log. There is no contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste; the core statement is front-loaded and the usage guidance in the second sentence earns its place. Nothing is repeated from the schema or annotations.

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?

For a simple read-only viewer with all-optional parameters, the description covers the core purpose and a realistic use case, while the schema documents the parameters and annotations cover the safety profile. Minor gaps remain — no response shape and no ordering semantics — but these are small for a log-viewing tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents five of six parameters, including the enums for action and entity_type and the SAGA_PROJECT default for project_id. The description adds little parameter-specific meaning — only a loose tie between session review and the 'since' parameter — so the high-coverage baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('View') and resource ('the activity log') with a clear content contract ('showing what changed and when'), which is unambiguous about the core function. However, it does not explicitly differentiate from siblings — the closest conceptual neighbor, tracker_session_diff, could plausibly overlap with 'reviewing what happened since the last session.'

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 second sentence gives explicit when-to-use context: 'understanding recent progress or reviewing what happened since the last session.' This is stated directly rather than merely implied, but there are no exclusions or named alternatives, leaving a small gap if an agent wonders whether tracker_session_diff serves the session-review use case instead.

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

comment_addA

Add a comment to a task. Comments create a chronological discussion thread — useful for leaving breadcrumbs across sessions.

ParametersJSON Schema

Name	Required	Description
`author`	No	Author name (optional)
`content`	Yes	Comment text
`task_id`	Yes	Task ID to comment on

TDQS

A3.8/5.0

Behavior3/5

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

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds context about chronological threading but does not disclose potential side effects like updating task metadata. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, no fluff. Every sentence adds value.

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?

For a simple write tool with 3 parameters and no output schema, the description adequately covers purpose and use case. Could mention the return value or note that comments append to existing thread, but not essential.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear parameter descriptions. The tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Add a comment to a task' and elaborates on its purpose as creating a chronological discussion thread for cross-session context. It distinguishes from sibling tools like comment_list and task_create.

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

Usage Guidelines3/5

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

The description implies usage for leaving breadcrumbs across sessions but does not explicitly state when to use this tool versus alternatives like note_save or task_update. No direct guidance on exclusion criteria.

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

comment_deleteA

Idempotent

Remove a comment (soft delete). The row is kept for the audit trail but hidden from comment_list and task_get. Use this to retract a comment that turned out to be wrong or stale. Reversible with comment_restore.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Comment ID to remove
`reason`	No	Why the comment is being removed (recommended — it stays in the audit trail)
`deleted_by`	No	Who removed it (optional)

TDQS

A4.9/5.0

Behavior5/5

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

Goes well beyond the annotations by revealing that the row is retained for the audit trail, is hidden from listing/reading operations, and can be restored. This is exactly the kind of non-obvious behavioral context that annotations alone do not capture.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no wasted words. The core behavior is front-loaded, followed by the key consequence and the recovery path. Every sentence earns its place.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple 3-parameter, no-output-schema tool, the description covers the operation's effect, visibility changes, audit implications, and reversibility. Nothing essential is missing for an agent to invoke this tool correctly.

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?

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful context for the 'reason' parameter by noting it stays in the audit trail, which deepens the agent's understanding of what to supply and why.

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?

Description states a specific verb ('Remove'), a specific resource ('a comment'), and clarifies that this is a soft delete with concrete visibility consequences (hidden from comment_list and task_get). It clearly distinguishes this from comment_add and comment_restore even without exploring schemas.

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

Usage Guidelines5/5

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

Explicitly says to use this to retract a comment that is wrong or stale, and names the recovery alternative ('Reversible with comment_restore'). This gives the agent clear selection criteria between the delete and restore operations.

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

comment_listA

Read-onlyIdempotent

List comments on a task in chronological order. Comments removed with comment_delete are hidden by default; pass include_deleted to see them with their removal reason.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes	Task ID
`include_deleted`	No	Include comments that were removed (soft-deleted). Off by default.

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds non-obvious behavioral detail beyond those annotations: results are chronological, soft-deleted comments are hidden by default, and passing include_deleted reveals them along with their removal reason. This materially improves the agent's understanding without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence states the action, resource, and ordering; the second explains the conditional flag. Every clause earns its place and the most important information is front-loaded.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with two simple parameters, strong annotations, and no output schema, the description is complete. It covers what is listed, the ordering, the default filtering behavior, and the purpose of the optional parameter. There are no critical gaps that would prevent correct invocation.

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 adds value beyond the schema by explaining that include_deleted surfaces removed comments 'with their removal reason' and by clarifying the chronological ordering, which gives the agent a better sense of what the output will be. This goes slightly beyond the schema's own parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('comments on a task'), and adds 'chronological order' to define the scope and output semantics. It is immediately distinguishable from sibling comment tools like comment_add, comment_delete, and comment_restore by its read-oriented action and the explicit reference to comment_delete.

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

Usage Guidelines5/5

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

The description clearly establishes the core use case: retrieving comments for a task. It also gives concrete guidance on the include_deleted parameter, explicitly stating that removed comments are hidden by default and explaining when to set the flag. This is sufficient guidance given that no alternative comment-listing sibling exists.

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

comment_restoreA

Idempotent

Restore a comment previously removed with comment_delete.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Comment ID to restore

TDQS

A4/5.0

Behavior3/5

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

Annotations already provide the key behavioral traits: readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the useful precondition that the comment must have been removed with comment_delete, which is context beyond the annotations. However, it does not disclose outcomes such as whether the restored comment returns to its original position or any error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no filler. The action and precondition are front-loaded, making it immediately scannable for an agent.

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?

For a simple one-parameter mutation with rich annotations and full schema coverage, the description is nearly complete. It could improve slightly by stating what happens after a successful restore or what the response is, but the current combination of schema, annotations, and description is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already states 'Comment ID to restore.' The tool description adds no additional meaning about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Restore') and resource ('comment'), and clarifies it applies to comments previously removed with comment_delete. This distinguishes it from comment_delete, comment_add, and comment_list without needing to open the 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 clearly indicates the intended use case: undoing a prior comment_delete. It references the relevant sibling tool and context. It does not explicitly list when not to use the tool, but the precondition is specific enough for an agent to route correctly.

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

epic_archiveA

Idempotent

Archive or unarchive an epic. Archived epics and their tasks drop out of listings, the dashboard and search unless include_archived is set. For putting finished work out of sight without cancelling it; nothing is deleted.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`archived`	No	true to archive, false to bring it back

TDQS

A4.2/5.0

Behavior4/5

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

Beyond the annotations, the description discloses important behavioral effects: archived epics and their tasks drop out of listings, the dashboard, and search unless include_archived is set. It also confirms that no data is deleted, which complements the idempotentHint and destructiveHint annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and efficiently ordered: the core action comes first, followed by the observable side effects and the intended use case. Every sentence earns its place, and there is no redundant or filler content.

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?

For a two-parameter tool with annotations covering idempotence and non-destructiveness, the description is nearly complete: it explains the action, the side effects on visibility, and the non-destructive nature. It does not describe expected return values or permissions, but with no output schema and a simple interface, this is not a significant gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents the archived parameter clearly ('true to archive, false to bring it back'), and the description reinforces this with 'archive or unarchive.' However, the required id parameter has no schema description and the tool description does not explicitly explain that id refers to the epic identifier, leaving a minor gap at 50% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource pair, 'archive or unarchive an epic,' and clearly explains the state change. It also distinguishes the operation from deletion by stating 'nothing is deleted,' which removes ambiguity about what the tool does.

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 gives a clear use case: putting finished work out of sight without cancelling it, which implies it should be used instead of destructive deletion or a regular update. It does not explicitly name sibling alternatives or state when not to use it, but the context is strong enough for an agent to make the right call.

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

epic_createA

Create an epic within a project. Epics group related tasks into a feature or workstream.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	Epic name
`tags`	No
`branch`	No	Branch to scope this epic to: "current" = active branch, omit/"" = branch-agnostic.
`status`	No		planned
`priority`	No		medium
`project_id`	Yes	Parent project ID
`description`	No	Epic description

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already cover read-only, destructive, and idempotency hints. The description adds the domain behavior of grouping tasks but does not disclose extra operational details such as whether the project must already exist, how duplicates are handled, or what happens after creation. It does not contradict the annotations.

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?

The description is two sentences and directly states the action and conceptual purpose without fluff. It is well front-loaded, though the second sentence could have provided operational guidance instead of repeating the obvious epic concept.

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

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has seven parameters and no output schema, and the description only covers the high-level purpose. Required parameters can be inferred, and the schema handles enums and defaults, but the description does not mention the expected return value, prerequisites, or behavior of optional fields. It is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 57%, and the description adds essentially no parameter-level meaning. It loosely relates 'project' to project_id and 'related tasks' to the epic's purpose, but it does not clarify tags, status, priority, or branch behavior beyond what the schema already provides. The description does not compensate for the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Create an epic within a project.' It also explains the concept of an epic by stating that epics group related tasks into a feature or workstream, which distinguishes it from sibling tools like epic_list, epic_update, and epic_archive.

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 gives clear context for when to use the tool: when creating an epic in a project to group related tasks. It does not explicitly mention alternatives or exclusions, but this is a creation tool and the intended use is straightforward.

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

epic_listA

Read-onlyIdempotent

List epics for a project with task counts and completion stats. Filter by status, priority or branch. Archived epics are hidden unless include_archived is set.

ParametersJSON Schema

Name	Required	Description
`branch`	No	Git branch filter: "current" = active branch, "" = branch-agnostic only, omit = all.
`status`	No
`priority`	No
`project_id`	Yes	Project ID
`include_archived`	No	Include archived epics and their tasks.

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context beyond the annotations by disclosing that archived epics are hidden by default unless include_archived is set, and that task counts and completion stats are included in the response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first states the core action and return value, the second covers filtering and archived behavior. Every sentence earns its place with no filler or repetition of schema details.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool, the description covers the purpose, the key filters, the archived default, and the return's analytical value. No output schema exists, but the description sufficiently communicates what the agent will receive. There is no missing critical context needed to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 60%, with status and priority lacking descriptions. The description compensates by identifying these as filters and explaining the archived behavior. The branch parameter's nuanced values ('current', '', omit) are already documented in the schema, so the description need not repeat them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), a clear resource ('epics for a project'), and the value-add ('task counts and completion stats'). This clearly distinguishes it from sibling tools like project_list, task_list, and the mutation-focused epic_create/epic_update/epic_archive.

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 gives clear context for when to use the tool: listing epics with filtering by status, priority, or branch, and controlling archived visibility. It does not explicitly name alternatives or state when not to use it, but the resource and purpose are unambiguous enough for an agent to select it correctly.

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

epic_updateA

Idempotent

Update an epic. Pass only the fields you want to change. Set status to "cancelled" to soft-delete. Pass branch="current" to pin to the active branch, or empty string to clear.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Epic ID
`name`	No
`tags`	No
`branch`	No	Branch to scope this epic to: "current" = active branch, "" = clear.
`status`	No
`priority`	No
`sort_order`	No
`description`	No

TDQS

A4.6/5.0

Behavior5/5

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

Beyond annotations, it reveals that the update is partial, that setting status to 'cancelled' performs a soft-delete rather than a hard destruction, and that branch scoping can be pinned or cleared. These are exactly the behavioral details an agent needs. The description does not contradict the annotations: destructiveHint=false is consistent with soft-delete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler. The core action comes first, then the two non-obvious special behaviors (soft-delete and branch pinning) are stated in compact, actionable form.

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?

For an update tool with eight parameters and no output schema, the description covers the essential invocation semantics: partial updates, soft-delete, and branch scope. It does not state what the response returns, but that is not strictly required to invoke the tool correctly; the key edge cases are documented.

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?

The general instruction 'Pass only the fields you want to change' adds meaningful semantics to all optional parameters, clarifying that omitted fields are left untouched. The description also explains the special branch values and the special 'cancelled' status beyond the raw schema, which is valuable given only 25% schema description coverage. It does not elaborate on obvious fields like name/tags/priority, but their names and types are self-explanatory.

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?

'Update an epic' names the exact verb and resource, and 'Pass only the fields you want to change' signals PATCH-style partial update rather than full replacement. This also separates it from sibling creation/listing/archiving tools, and the soft-delete and branch behavior add precision.

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 gives concrete operational conditions: status 'cancelled' is the soft-delete path, and branch accepts either 'current' for active-branch pinning or an empty string to clear. It does not explicitly name sibling alternatives or state when not to use it, but the update-vs-create distinction is clear enough from the verb and sibling names.

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

note_deleteA

DestructiveIdempotent

Delete a note by ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Note ID

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds no further behavioral context (e.g., permanence of deletion, soft-delete behavior). Adequate given annotation coverage.

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?

Single sentence with 5 words, no wasted text. However, could be slightly more informative while remaining concise.

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?

For a simple delete tool with one required parameter and no output schema, the description is sufficient. It lacks mention of return value or side effects, but annotations cover the destructive nature.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter 'id' described as 'Note ID'. Description adds no extra semantics beyond 'by ID'. Baseline score for high coverage.

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?

Description clearly states the action 'delete' and the resource 'note' with the method 'by ID'. It is unambiguous and distinct from siblings like note_list, note_save, note_search.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives (e.g., note_save for updating, or archiving). No exclusions or prerequisites mentioned.

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

note_listB

Read-onlyIdempotent

List notes with optional filters. Returns notes sorted by most recent first.

ParametersJSON Schema

Name	Required	Description
`tag`	No	Filter by a single tag
`limit`	No
`note_type`	No
`project_id`	No	Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database.
`related_entity_id`	No
`related_entity_type`	No

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already communicate that the tool is read-only, idempotent, and non-destructive. The description adds a useful observable behavior: notes are sorted most recent first. It does not contradict the annotations, though it does not mention result limits or other runtime behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The core action is front-loaded, and the sorting behavior is stated in a second short sentence. Every word earns its place.

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

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the basic list behavior and ordering, which is adequate for a simple read-only tool. However, with six optional parameters and no output schema, key details like available filters, default limits, and result shape are left unspecified, making the definition only partially complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 33% schema description coverage and six parameters, the description needed to explain filter semantics but only says 'optional filters.' It does not clarify note_type, related_entity_id/related_entity_type pairing, the SAGA_PROJECT default, or the default limit, so it provides little value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (List) and resource (notes), and adds helpful detail about optional filtering and sorting by recency. It is easy to understand what the tool does, though it does not explicitly differentiate from the sibling note_search tool.

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

Usage Guidelines3/5

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

The phrase 'optional filters' implies this is the appropriate tool when you need to list or filter notes, so usage is inferable. However, there is no explicit guidance about when to prefer note_search instead, nor any exclusions or alternative routing.

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

note_saveA

Create or update a note: decisions, context, progress, meetings, blockers, technical detail, releases. With id, updates; without, creates.

ParametersJSON Schema

Name	Required	Description	Default
`id`	No	Note ID (omit to create new)
`tags`	No
`title`	Yes	Note title
`content`	Yes	Full note content (markdown supported)
`note_type`	No		general
`related_entity_id`	No	ID of the related entity
`related_entity_type`	No	Link note to an entity

TDQS

A4.2/5.0

Behavior4/5

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

The description discloses the key state-dependent behavior that passing an id updates an existing note while omitting it creates a new one. The annotations already mark readOnly=false, and the description adds meaningful context beyond that without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence carries the core operation, the create/update distinction, and the supported content categories with no filler. Every word earns its place.

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?

The schema covers required title/content, optional tags, note_type, and entity linking, while the description covers the core save behavior and the id-based update condition. The definition is sufficient for a straightforward note-save tool even though it does not describe the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 71%, so the schema already explains most parameters. The description reinforces the id semantics and expands the note_type enum into practical categories like decisions, meetings, blockers, and releases, but it adds nothing about tags or related_entity fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the exact operation, 'Create or update a note', and lists the content categories it supports. This clearly distinguishes it from sibling read, search, list, and delete note tools without needing to open their schemas.

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 id-based behavior is explicit: 'With id, updates; without, creates,' which tells the agent exactly how to choose the create versus update path. It does not explicitly name sibling alternatives, but the mutating verb and content scoping make its role as the write tool for notes evident.

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

note_searchB

Read-onlyIdempotent

Search across note titles and content by keyword.

ParametersJSON Schema

Name	Required	Description
`limit`	No
`query`	Yes	Search keywords
`note_type`	No

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, covering the safety profile. The description adds the scope ('titles and content') but does not disclose details like search behavior (e.g., fuzzy matching) or performance considerations. With annotations present, this is adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence of 8 words, with no extraneous information. It efficiently communicates the core action.

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

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the three parameters (one enum), no output schema, and no description of return value or behavior, the description is incomplete. It fails to inform the agent about filtering by note_type, the default limit, or the structure of search results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (33%), with only 'query' having a description ('Search keywords'). The other parameters, note_type and limit, lack descriptions in both schema and tool description. The description does not explain how note_type filters results or that limit defaults to 20, so it adds minimal meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: searching across note titles and content by keyword. The verb 'Search' and resource 'note titles and content' are specific, distinguishing it from sibling tools like note_list or note_save.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool instead of alternatives like note_list, nor any conditions or exclusions. The agent receives no help in deciding between similar note-related tools.

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

project_createB

Create a new project. Projects are the top-level container for all work.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	Project name
`tags`	No	Tags for categorization
`status`	No	Project status	active
`description`	No	Project description

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already indicate this is a non-read-only, non-destructive operation. The description adds that projects are top-level containers, but does not disclose side effects, authentication needs, or rate limits. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences that are front-loaded with the action and provide a brief context. No unnecessary words or redundancy.

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

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite good annotations and schema, the description omits return value information (no output schema) and does not describe default behaviors for optional parameters like status. A more complete description would mention created project details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100% with descriptions for all parameters. The description adds no additional parameter information beyond the schema, so baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'create' and the resource 'projects', and explains that projects are top-level containers. This distinguishes it from siblings like project_list and project_update.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like project_update or epic_create. The description does not mention prerequisites, context, 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.

project_listA

Read-onlyIdempotent

List all projects with epic/task counts and completion percentages. Optionally filter by status.

ParametersJSON Schema

Name	Required	Description	Default
`status`	No	Filter by status

TDQS

A4.2/5.0

Behavior4/5

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

Annotations confirm it's read-only and idempotent; description adds that it returns counts and percentages, providing useful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence that front-loads the key purpose and optional filter.

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?

No output schema but description explains return values (counts, percentages). Lacks pagination details, but sufficient for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter status is fully described in schema; description only restates the filter option without adding new meaning.

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?

Clearly states it lists projects with epic/task counts and completion percentages, distinguishing it from other list tools like epic_list or task_list.

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?

Mentions optional filtering by status, but lacks explicit guidance on when to use vs alternatives; however, the purpose is clear enough for correct selection.

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

project_updateA

Idempotent

Update a project. Pass only the fields you want to change. Set status to "archived" to soft-delete.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Project ID
`name`	No
`tags`	No
`status`	No
`description`	No

TDQS

A4/5.0

Behavior4/5

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

Annotations already indicate the tool is not read-only and not destructive, with idempotency. The description adds value by disclosing the soft-delete behavior (setting status to 'archived') and the partial update semantics, which go beyond what annotations provide. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprised of two concise and front-loaded sentences, delivering key information without extraneous content. Every sentence adds value: the first states the primary action and partial update, the second explains the soft-delete use of the 'status' parameter.

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?

Given the tool's moderate complexity (5 parameters, partial update, soft-delete) and the absence of an output schema, the description covers the essential behavioral aspects. It is missing details about response format, error handling, or authentication, but the provided information is sufficient for basic correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (20%), with only 'id' described. The description provides high-level guidance on partial updates and the effect of the 'status' parameter (soft-delete), but it does not elaborate on other parameters like 'name', 'description', or 'tags'. This partially compensates but insufficiently addresses the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Update a project' as the primary action, distinguishing it from creation or listing tools. It also specifies the partial update behavior and the special effect of setting status to 'archived' for soft-deletion, leaving no ambiguity about the tool's purpose.

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

Usage Guidelines3/5

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

The description advises to 'Pass only the fields you want to change,' implying partial updates, and explains soft-delete via status. However, it lacks explicit guidance on when to use this tool versus alternatives like project_create (for new projects) or other sibling tools, and does not mention prerequisites or restrictions.

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

subtask_createA

Create subtasks (checklist items) for a task. Pass titles as an array — one string per subtask — and each becomes its own record. New subtasks are appended after any that exist.

ParametersJSON Schema

Name	Required	Description
`titles`	Yes	Subtask titles, one per array item — e.g. ["Write it", "Test it"]. Always an array, even for a single subtask.
`task_id`	Yes	Parent task
`depends_on`	No	Siblings each new subtask waits on

TDQS

A4.4/5.0

Behavior4/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses two useful behavioral traits: each title becomes its own record and new subtasks are appended after existing ones. This gives the agent a concrete expectation of side effects; no contradiction with the annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each contributing distinct information: what the tool creates, how titles map to records, and where the records are placed. The key verb and resource are front-loaded with no 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?

For a 3-parameter tool with fully described schema, the core behavior and placement semantics are covered. It does not describe the return value or the exact interaction of depends_on with multiple new subtasks, but these are relatively minor given the schema coverage and the absence of nested objects or enums.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the titles array-to-record mapping and append behavior, which the schema alone does not fully convey. It appropriately leaves task_id and depends_on details to the schema, which already documents them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Create subtasks (checklist items) for a task.' This clearly differentiates it from the sibling tools subtask_update, subtask_reorder, and subtask_delete, and from task_create, by saying it creates child checklist records rather than tasks or updated subtasks.

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?

It communicates the clear usage context: add checklist items to an existing task, with titles passed as an array. It does not explicitly state when not to use it or name alternative tools, so it falls short of the strongest routing guidance, but the context is unambiguous.

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

subtask_deleteC

DestructiveIdempotent

Delete one or more subtasks. Accepts a single ID or array of IDs.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes	Subtask IDs to delete — e.g. [4, 7]. Always an array, even for one.

TDQS

C2.6/5.0

Behavior2/5

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

The annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true) already cover the core safety profile. The description adds no side-effect context such as permanence, cascade behavior, or error behavior, and its only extra behavioral claim—accepting a single ID—is false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is short and front-loaded, but the second sentence does not earn its place: it repeats schema information and introduces an inaccuracy. A clean one-sentence description that just said 'Delete one or more subtasks by ID' would be better.

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

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter delete with no output schema, the core requirements are mostly covered by the schema, but the description introduces a conflicting input format and omits any return or error semantics. An agent cannot reliably know what happens after deletion.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully documents ids at 100% coverage and explicitly says 'Always an array, even for one.' The description directly contradicts this by saying it accepts a single ID, which could cause an agent to send an integer instead of an array. This is actively harmful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and target: 'Delete one or more subtasks.' This tells an agent exactly what the tool does and is enough to distinguish it from task_delete, note_delete, and comment_delete without inspecting the schema.

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

Usage Guidelines2/5

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

No guidance is given about when to prefer this tool over alternatives such as task_delete, subtask_update, or subtask_reorder. There are no exclusions, prerequisites, or context cues beyond what the name implies.

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

subtask_reorderA

Idempotent

Reorder a task subtask list. Pass IDs in the order you want; any omitted keep their relative order at the end.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes	Parent task
`ordered_ids`	Yes	Subtask IDs, in order

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already mark it idempotent and non-destructive; the description adds the useful behavior that omitted IDs keep their relative order at the end. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences that front-load the action, then clarify the only non-obvious detail. No 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?

For a simple two-parameter mutation, this covers invocation semantics well. It does not discuss edge cases like duplicate or foreign IDs, or return values, but these are not critical for selecting the tool correctly.

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%, but the description adds the key array-order rule and explicitly instructs the caller to pass IDs in desired order, which is more than the schema's 'in order' note.

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?

Description uses a specific verb and resource: 'Reorder a task subtask list'. This clearly differentiates it from sibling subtask_create/update/delete tools.

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

Usage Guidelines3/5

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

The use case is implied by 'reorder', and the partial-order semantics tell the agent how to supply IDs, but it never states when not to use it or points to an alternative for moving or updating subtasks.

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

subtask_updateA

Idempotent

Update a subtask title, status or position. depends_on sets what it waits on, blocks the inverse; both replace the set, [] clears. Starting or finishing one with unmet prerequisites needs force.

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`force`	No	Proceed despite unmet prerequisites. Only when a human says the blocker no longer applies, never on your own initiative. Logged.
`title`	No
`blocks`	No	Siblings that wait on this one — inverse of depends_on
`status`	No
`depends_on`	No	Siblings this one waits on (replaces the set)
`sort_order`	No

TDQS

A3.9/5.0

Behavior4/5

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

The description adds valuable behavior beyond the annotations: depends_on and blocks are inverse relationship setters, both replace the existing set, [] clears, and force is required to bypass unmet prerequisites. It does not contradict the idempotentHint or destructiveHint annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and information-dense. Three sentences cover the main purpose, relationship semantics, and the force requirement without wasted words, and the core update action is front-loaded.

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?

For a 7-parameter mutation tool with no output schema, the description covers the critical behavioral nuances: relationship replacement, clearing, and prerequisite enforcement. It does not describe return values or explicitly enumerate all status values, but the schema covers the enum and the essential calling context is present.

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?

With only 43% schema description coverage, the description compensates meaningfully by explaining the semantics of depends_on, blocks, and force, including set replacement and clearing. It also maps 'position' to sort_order, but leaves id, title, and status mostly self-explanatory without deep detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Update a subtask title, status or position.' It gives the core scope of the tool and distinguishes it from task-level siblings by focusing on subtasks, though it does not explicitly contrast it with subtask_reorder, which also deals with position.

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

Usage Guidelines3/5

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

Usage context is implied rather than explicit: the description explains fields and force behavior, but does not state when to choose this tool over subtask_reorder or other subtask operations. The force caveat does give a concrete conditional for starting/finishing with unmet prerequisites.

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

task_batch_updateA

Idempotent

Update multiple tasks at once. Useful for changing status of several tasks (e.g., mark 3 tasks as done) or reassigning tasks.

ParametersJSON Schema

Name	Required	Description
`ids`	Yes	Task IDs to update
`force`	No	Proceed despite unmet prerequisites. Only when a human says the blocker no longer applies, never on your own initiative. Logged.
`status`	No
`priority`	No
`assigned_to`	No

TDQS

A3.9/5.0

Behavior3/5

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

Annotations already communicate that the tool is a non-destructive write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds no behavioral detail beyond the use cases; it does not mention partial-failure behavior, whether unspecified fields are left untouched, or any side effects. This is acceptable but unremarkable given the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The core action is front-loaded, followed by concrete examples that aid selection. The description is appropriately sized for its purpose.

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

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main use cases but, with no output schema, the agent is left unaware of what a successful or partial batch update returns. It also omits how partial failures are handled and does not mention the 'force' prerequisite bypass, which is documented only in the schema. This is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 40% schema description coverage, the description partially compensates by explaining that 'status' is changeable and 'assigned_to' is for reassignment. However, it says nothing about 'priority', and the schema itself offers no description for status, priority, or assigned_to, leaving that parameter under-specified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Update multiple tasks at once') and reinforces it with concrete examples (marking tasks done, reassigning). The 'multiple' qualifier distinguishes it from the sibling task_update without ambiguity.

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 phrase 'Useful for changing status of several tasks... or reassigning tasks' gives clear contexts for choosing this tool. It does not explicitly name task_update as the single-task alternative or state when not to use it, so it falls just short of a 5.

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

task_createA

Create a task within an epic. Tasks are the primary unit of work.

ParametersJSON Schema

Name	Required	Description	Default
`tags`	No
`title`	Yes	Task title
`status`	No		todo
`epic_id`	Yes	Parent epic ID
`due_date`	No	Due date (YYYY-MM-DD)
`priority`	No		medium
`depends_on`	No	Task IDs this task depends on
`source_ref`	No	Link to source code location
`assigned_to`	No	Assignee name
`description`	No	Task description
`estimated_hours`	No	Estimated hours

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already indicate this is a mutating, non-idempotent operation, and the description confirms the core behavior by stating it creates a task. It adds the parent-scope detail ('within an epic') but does not explain side effects, response behavior, or failure when an epic_id is invalid. There is no contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the core action front-loaded before context. Every phrase earns its place, and there is no redundant restatement of the parameter schema or annotations.

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

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters, a nested source_ref object, and no output schema, the description is too sparse. It does not state what a successful creation returns, how to handle an invalid or missing epic_id, or which optional fields are commonly relevant when creating a task. The schema covers parameter details, but important behavioral and return context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 73%, so most parameters are already documented in the schema. The description adds only the 'within an epic' context, which maps to epic_id but does not enrich the meaning of the other 10 parameters beyond their existing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb and resource: 'Create a task within an epic.' This clearly separates it from task_update, task_batch_update, and subtask_create. The extra sentence 'Tasks are the primary unit of work' reinforces the tool's role and scope.

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

Usage Guidelines3/5

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

The description gives useful context that tasks belong to an epic, and 'primary unit of work' hints at top-level task creation. However, it never explicitly says when to use this instead of subtask_create, task_update, or other related tools. There are no clear exclusions or alternatives, so usage guidance is only implied.

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

task_deleteA

Idempotent

Remove a task (soft delete). Only 'todo' tasks — anything further along has history worth keeping. The row is kept and hidden from listings; task_restore brings it back.

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`reason`	No	Why it is being removed (kept in the audit trail)
`deleted_by`	No

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the annotations, the description discloses the soft-delete behavior: the row is kept, hidden from listings, and restorable via task_restore. This directly explains why destructiveHint is false and adds operational context the annotations don't provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences front-load the core meaning, then add the scope restriction and the restore behavior. Each sentence contributes new, non-redundant information.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description covers what mutates, what is preserved, the visibility effect, and the recovery path. The annotations already cover write/read-only and idempotence, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33%, so the description should compensate for undocumented parameters. It does not explain `deleted_by` or expand on `id`, and while `reason` has a schema description, the tool description adds no parameter-level meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact action and resource ('Remove a task') and immediately clarifies it is a soft delete, which differentiates it from permanent-delete tools. It also names the inverse tool (task_restore), helping an agent distinguish this from restoration and other delete siblings.

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

Usage Guidelines4/5

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

The description explicitly scopes usage to 'todo' tasks and warns that further-along tasks should not be removed because their history matters. It does not name an explicit alternative tool for non-todo tasks, but the boundary is clear enough that an agent can decide against calling it.

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

task_getA

Read-onlyIdempotent

Get a single task with full details including all subtasks, related notes, comments, and dependencies.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Task ID

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by specifying the full scope of returned data (subtasks, notes, comments, dependencies), providing behavioral context beyond the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that fronts the purpose and efficiently lists included details. No superfluous content.

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?

For a simple get tool with one parameter and no output schema, the description adequately explains the return scope. Could optionally mention error conditions or permissions, but annotations cover safety and idempotency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'id', which is described as 'Task ID'. The description does not add further meaning or constraints beyond the schema, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('a single task'), and clearly outlines the included details (subtasks, notes, comments, dependencies). This effectively distinguishes it from sibling tools like task_list or task_create.

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

Usage Guidelines3/5

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

The description implies usage for retrieving a single task by ID, but does not explicitly state when to use it over alternatives like task_list. No exclusions or when-not scenarios are mentioned, relying on the user or agent to infer context from the sibling list.

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

task_listA

Read-onlyIdempotent

List tasks; without epic_id, across all epics. Includes subtask and dependency counts. Rows are compact: nulls and metadata dropped, descriptions cut to 120 chars (task_get for full). branch="current" restricts to the active git branch.

ParametersJSON Schema

Name	Required	Description
`tag`	No	Filter by tag
`limit`	No	Max results
`branch`	No	Git branch filter: "current" = active branch, "" = branch-agnostic only, omit = all.
`status`	No
`epic_id`	No	Filter by epic (omit for all tasks)
`sort_by`	No	Omit to follow the arrangement set by task_reorder, falling back to priority. priority (critical first), created (newest), due_date (earliest), status (actionable first), manual.
`priority`	No
`project_id`	No	Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database.
`assigned_to`	No	Filter by assignee
`include_deleted`	No	Include removed tasks.
`include_archived`	No	Include archived epics and their tasks.

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses meaningful behavior: compact rows, dropped nulls/metadata, 120-char description truncation, subtask and dependency counts, and branch filtering semantics. This is valuable additional context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences carry all the essential information without waste. The main purpose is front-loaded and the truncation/alternative guidance follows naturally.

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?

For an 11-parameter read-only listing tool without an output schema, the description covers the key behaviors: scope, returned count summaries, compaction rules, and branch filtering. It lacks a full return shape description, but that is not critical for invoking the tool correctly.

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 82%, so the schema already documents most parameters. The description adds interpretive value for epic_id and branch, specifically explaining the 'without epic_id' behavior and the meaning of branch='current', which goes beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists tasks and clarifies the default scope ('without epic_id, across all epics'). It also differentiates from task_get by noting truncated descriptions and directing users to task_get for full details.

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 provides useful context for when to use this tool: when a compact cross-epic list is needed, and when full details are required, task_get is the alternative. It could be more explicit about exclusions, but the guidance is clear enough.

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

task_lock_descriptionA

Idempotent

Lock or unlock a task's description. While locked, task_update refuses to change it — a guard against rewriting the spec when you meant to add a comment. Every other field still changes freely.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Task ID
`locked`	No	true to lock, false to unlock

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already indicate mutation, idempotence, and non-destructiveness. The description adds valuable context: task_update refuses the change while locked, and every other field still changes freely. This explains the operational consequence of locking beyond what annotations state. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no redundancy: purpose, mechanism, and scope. The core verb and resource are front-loaded, and every sentence adds useful information.

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?

For a low-complexity tool with two simple parameters and a fully documented schema, the description covers purpose, behavior, and side effects. It could mention the intended alternative action more explicitly, but nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents both parameters completely, including the boolean meaning and default for 'locked'. With 100% schema coverage, the description need not repeat parameter details. Baseline 3 is appropriate because the description adds no extra parameter-level semantics.

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 clear verb and resource: 'Lock or unlock a task's description.' It goes further by distinguishing itself from task_update, explaining that the tool guards the description field specifically. In a large sibling list, this uniquely identifies the tool's role.

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?

Gives a concrete use case: preventing accidental spec rewrites when the intent is to add a comment. It also clarifies that other fields remain editable, helping the agent understand what the tool does not affect. It stops short of explicitly naming 'comment_add' as the alternative, so not a full 5.

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

task_reorderA

Idempotent

Set the order of an epic's tasks. Omitted IDs keep their relative order at the end. task_list then follows this arrangement by default.

ParametersJSON Schema

Name	Required	Description	Default
`epic_id`	Yes	Parent epic
`ordered_ids`	Yes	Task IDs, in order

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already mark this as a non-read-only, idempotent, non-destructive mutation. The description adds valuable behavior beyond that: omitted IDs retain their relative order at the end, and task_list follows the arrangement by default. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences deliver the core operation and the two most important behavioral details with no filler. The primary action is front-loaded.

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?

For a simple two-parameter reorder tool, the description covers the operation, the partial-ordering rule, and the downstream effect on task_list. It does not describe return values or error conditions, but those are not clearly necessary for correct invocation, given the simple schema.

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 goes beyond the schema by defining what happens to IDs not present in ordered_ids, which clarifies the array's partial-order semantics. It also ties epic_id to the epic scope.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Set the order of an epic's tasks.' This clearly identifies the operation and scope, and the distinction from subtask_reorder is implicit since it operates on epic tasks rather than subtasks.

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

Usage Guidelines3/5

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

The description implies the tool is used when an epic's tasks need a desired ordering and notes the downstream effect on task_list. However, it does not state when to choose this over alternatives like subtask_reorder or task_batch_update, nor does it provide any exclusion conditions.

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

task_restoreA

Idempotent

Restore a task removed with task_delete.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already carry the key safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description need not restate those. It adds the useful inverse relation to task_delete, but does not disclose consequences such as whether subtasks/comments are restored, error behavior for missing ids, or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence, 'Restore a task removed with task_delete,' contains the action, resource, and precondition with zero filler. No restructuring or trimming is needed.

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?

Given the tool's simplicity (one required id, no nested objects, no output schema) and the annotations covering idempotency and non-destructiveness, the description is nearly complete. It lacks only finer behavioral details like return value or effects on dependent objects, which are minor for this operation.

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?

The schema provides only 'id: integer' with no description, and the description bridges that gap by implying the id identifies a task that was removed with task_delete. For a single-parameter tool this is sufficient to infer the parameter's meaning, though it does not spell out the id semantics explicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description immediately states a clear verb and object: 'Restore a task...'. It also names the sibling operation it reverses ('removed with task_delete'), which distinguishes it from other restore/crud tools like comment_restore without requiring schema inspection.

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 phrase 'removed with task_delete' gives a clear precondition and when to use the tool: to undo a prior task_delete. It does not explicitly enumerate alternatives or exclusion cases, but the task/comment split among siblings makes the intended use unambiguous.

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

task_updateA

Idempotent

Update a task; pass only fields to change. Completing it while subtasks are unfinished is refused unless force is set.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Task ID
`tags`	No
`force`	No	Proceed despite unmet prerequisites. Only when a human says the blocker no longer applies, never on your own initiative. Logged.
`title`	No
`status`	No
`due_date`	No
`priority`	No
`depends_on`	No	Task IDs this task depends on (replaces existing)
`sort_order`	No	Manual position within the epic; lower sorts first. Use task_reorder instead of setting this by hand.
`source_ref`	No	Link to source code location
`assigned_to`	No
`description`	No
`actual_hours`	No
`estimated_hours`	No

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already indicate this is not read-only and not destructive, and mark it idempotent. The description adds non-obvious behavior beyond that: completing a task with unfinished subtasks is refused unless force is set. This is meaningful behavioral context, though it does not describe result shape or side effects like logging.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The first sentence conveys purpose and usage rule, and the second adds the critical guard condition. Every part earns its place.

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

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 14 parameters, a nested source_ref object, enums, and no output schema, the description is somewhat thin. It covers partial updates and the completion guard, but leaves the agent to infer return behavior, array replacement semantics, and reordering guidance. Some of that is handled in the schema, so the tool is usable, but not fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 36%, so the description needs to compensate, and it does only partially. 'Pass only fields to change' is valuable across all parameters, and the force/completion relationship is useful. However, many parameters remain undocumented in both the description and the schema, even if their names are somewhat self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Update a task,' a specific verb and resource, and adds useful patch semantics with 'pass only fields to change.' It does not explicitly contrast with task_batch_update or task_reorder, so it misses the top mark for sibling differentiation.

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

Usage Guidelines3/5

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

It provides a clear invocation style ('pass only fields to change') and a specific conditional refusal rule, but it never says when to prefer task_batch_update, subtask_update, or task_reorder. Usage is implied rather than explicitly contrasted with alternatives.

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

template_applyA

Apply a template to create tasks in an epic. Replaces {variable} placeholders with provided values.

ParametersJSON Schema

Name	Required	Description
`epic_id`	Yes	Epic to create tasks in
`variables`	No	Key-value pairs for {variable} substitution (e.g., {"feature": "auth"})
`template_id`	Yes	Template ID to apply

TDQS

A4/5.0

Behavior4/5

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

Annotations already indicate a non-read-only, non-destructive mutation. The description adds specific behavior—placeholder substitution and task creation—that enriches the agent's understanding without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences front-load the core action and key behavior (placeholder replacement). No extraneous words; every sentence earns its place.

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?

For a tool with 3 params, no output schema, and nested objects, the description covers purpose and substitution behavior. Missing details like error handling or permissions are acceptable given context signals, though a note on idempotency would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for all three parameters. The description adds no new param-level detail beyond reinforcing the variable substitution mechanism, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool applies a template to create tasks in an epic. This verb-object structure distinguishes it from siblings like template_create, task_create, or epic_create.

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

Usage Guidelines3/5

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

The description implies this tool is for converting a template into tasks within an epic, but does not explicitly contrast with alternatives like manually creating tasks or using other template tools. No when-not or exclusion guidance is provided.

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

template_createA

Create a reusable set of tasks that can be instantiated into any epic. {variable} placeholders are filled in on apply.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Template name (must be unique)
`tasks`	Yes	The tasks this template creates.
`description`	No

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already mark this as non-readonly, and the description adds useful behavior: the created artifact is not immediately a task list; it is a reusable template whose placeholders are resolved when applied. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core purpose and a useful placeholder detail. No filler or repetition of schema field names.

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?

For a relatively simple three-parameter creation tool, the description conveys purpose, reusability, and placeholder behavior. It does not explain return behavior, but no output schema exists and the create action is straightforward; the main gap is leaving the optional top-level description parameter undefined.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds placeholder behavior for task title/description beyond the schema, which is valuable. However, the top-level 'description' parameter is unexplained, and schema coverage is only 67%, so the description does not fully compensate for the missing parameter semantics.

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?

Clearly states a specific verb ('Create') and resource ('reusable set of tasks'), and distinguishes this from template_apply by explaining templates are instantiated later. The mention of placeholders further defines the tool's unique role among siblings.

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

Usage Guidelines4/5

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

The description gives clear context: use it to create reusable task templates with variable placeholders that get filled at apply time. It does not explicitly name alternatives or state when not to use it, but the create-vs-apply distinction is strongly implied.

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

template_deleteA

DestructiveIdempotent

Delete a task template.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Template ID

TDQS

A3.6/5.0

Behavior3/5

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

The description aligns with annotations (destructiveHint=true) but adds no additional behavioral context beyond what annotations already convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, complete sentence with no wasted words, achieving maximum conciseness.

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?

For a simple delete operation with one parameter and rich annotations, the description is adequate, though it could mention return values or side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description does not add meaning beyond the schema's parameter description (Template ID). Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description "Delete a task template." uses a specific verb (Delete) and a clear resource (task template), distinguishing it from sibling tools like template_create or template_apply.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives, such as when not to delete a template that might be in use, or any prerequisites.

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

template_listA

Read-onlyIdempotent

List task templates. Pass include_tasks to see what each one actually creates.

ParametersJSON Schema

Name	Required	Description	Default
`include_tasks`	No	Return each template's task definitions, not just a count.

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, covering the safety profile. The description adds a small behavioral note that include_tasks reveals what each template actually creates, which is useful context beyond the raw schema. There is no contradiction between the description and the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The core purpose is front-loaded, and the parameter guidance is neatly separated. Every word earns its place.

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?

This is a simple, low-complexity tool with one optional parameter and comprehensive annotations. The description covers the tool's purpose and the optional parameter's effect. It does not describe the default return shape, but that is a minor gap given no output schema exists and the parameter schema already implies a count-based default.

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 adds meaning by framing include_tasks as revealing what each template 'actually creates,' which clarifies its purpose more naturally than the schema's 'task definitions, not just a count.' This goes slightly beyond the schema without repeating it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List task templates.' The resource is clearly distinguished from related tools like task_list, template_create, and template_apply. The additional sentence about include_tasks reinforces what the tool is for, making the purpose unambiguous.

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

Usage Guidelines3/5

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

The description gives an implied usage context: use this tool to inspect templates, and optionally pass include_tasks to see their task definitions. It does not explicitly name alternatives or state when not to use this tool, but among the siblings no other tool lists task templates, so the intended context is reasonably clear.

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

template_updateA

Idempotent

Edit a template in place. Only the fields you pass change; tasks replace the whole list.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Template ID
`name`	No
`tasks`	No	Replaces every task. Omit to leave them alone. {variable} works in title and description.
`description`	No

TDQS

A4.2/5.0

Behavior4/5

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

The description goes beyond the annotations by disclosing partial-update semantics: only passed fields change, and tasks replace the entire list if provided. This is valuable behavioral context that the schema alone does not fully convey. There is no contradiction with the annotations; idempotent and non-destructive hints are compatible with this behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences convey the essential behavior with no filler. The main purpose is front-loaded, and the important task-replacement caveat is included without redundant explanation.

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?

For a partial-update tool with a small schema and no output schema, the description covers the key behavioral nuances: in-place editing and task-list replacement. It does not discuss alternative tools or edge cases, but the essential information needed to call the tool correctly is present.

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?

The description adds meaningful semantics by explaining the update model: omitted fields remain unchanged, while the tasks array replaces the full list. This compensates for the schema's lack of descriptions on the name and description parameters. The schema documents id and tasks directly, but the description clarifies how all fields behave.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool edits a template in place, which distinguishes it from template_create, template_delete, and template_apply. It also conveys that this is a partial update operation on an existing template, not a replacement of the template itself.

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

Usage Guidelines3/5

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

The description implies when to use this tool: to modify an existing template in place. However, it does not explicitly mention alternatives like template_create or template_apply, nor does it provide when-not-to-use guidance. The usage context is clear but left to inference.

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

tracker_dashboardA

Read-onlyIdempotent

Full project overview in one call: project, epics with task counts, stats, blocked and overdue tasks, recent activity and notes. Best first call when starting work. branch="current" scopes to the active git branch.

ParametersJSON Schema

Name	Required	Description
`branch`	No	Scope to a git branch: "current" = active branch, "" = branch-agnostic only, omit = all.
`project_id`	No	Project ID. Omit for a single-project database or when SAGA_PROJECT is set. Otherwise the first is used and the rest listed under other_projects.
`include_archived`	No	Include archived epics and their tasks.

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the aggregating behavior and the branch='current' scoping nuance, providing some extra context beyond annotations, though not deep behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: the first states the core purpose, the second gives usage context, and the third clarifies the branch parameter. Content is front-loaded and every sentence earns its place.

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 no output schema, the description does a good job enumerating the returned components (project, epics, stats, blocked/overdue tasks, activity, notes). It covers the main branch scoping too. 'Stats' is slightly vague, but the tool's dashboard nature makes the return shape sufficiently understandable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description is not required to document parameters. The branch='current' note in the description mirrors the schema's own wording and adds no significant new semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "Full project overview in one call" and lists concrete contents (project, epics with task counts, stats, blocked/overdue tasks, activity, notes). This clearly distinguishes the dashboard from sibling tools like task_list or epic_list.

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?

Explicitly says "Best first call when starting work," which gives a clear usage context. It does not name specific alternative tools or exclusions, but for an overview dashboard this is acceptable guidance.

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

tracker_exportA

Read-onlyIdempotent

Export a full project as nested JSON. Includes all epics, tasks, subtasks, comments, dependencies, and related notes. Useful for backup, migration, or sharing.

ParametersJSON Schema

Name	Required	Description	Default
`project_id`	No	Project ID to export (omit if only one project exists)

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe, idempotent read operation. The description adds valuable context about the export's content (all entities included), going beyond the structured data. It does not describe potential size limits or rate limits, but given the annotations, the bar is lower.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each adding value. The main action is front-loaded, and the supporting sentences clarify scope and use cases without redundancy. No waste.

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?

Given the tool's simplicity (one optional parameter, read-only, idempotent), the description is adequate. It specifies output format and included content, which compensates for the lack of an output schema. However, it could mention intended output structure or size considerations for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: the only parameter, project_id, is fully described in the schema. The description adds no additional parameter information. Per guidelines, with high coverage, baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (export), the resource (full project), and the format (nested JSON), with a detailed list of included elements. This specificity implicitly distinguishes it from sibling tools like tracker_import or tracker_session_diff, making the purpose unmistakable.

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 explicitly gives usage context: 'Useful for backup, migration, or sharing.' This provides clear context for when to use the tool, though it does not list alternatives or when not to use it, which would earn a 5.

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

tracker_importA

Import a project from JSON (matching tracker_export format). Creates all entities with new IDs and remaps references. Uses a transaction for atomicity.

ParametersJSON Schema

Name	Required	Description	Default
`data`	Yes	Full export JSON object from tracker_export

TDQS

A4.2/5.0

Behavior4/5

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

Beyond annotations, description reveals it creates new IDs, remaps references, and uses a transaction for atomicity. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with purpose, no wasted words.

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?

Given no output schema and single parameter, description adequately covers behavior. Could mention prerequisites (e.g., valid JSON format) but sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameter description already states it expects a full export JSON. Description adds no new parameter-level meaning beyond that.

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?

Description clearly states the tool imports a project from JSON, matching the tracker_export format. This distinguishes it from siblings like tracker_export and project_create.

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?

Implies usage when importing a previously exported project, but lacks explicit guidance on when not to use or alternatives. Context is clear.

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

tracker_initA

Idempotent

Initialize the tracker for a project. If the database is empty, creates a project with the given name. If a project already exists, returns its info.

ParametersJSON Schema

Name	Required	Description	Default
`project_name`	No	Name for a new project (only used if DB is empty)
`project_description`	No	Description for the new project

TDQS

A4.5/5.0

Behavior5/5

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

Annotations (idempotentHint=true) are supported by description's conditional logic. Description adds context beyond annotations: explains that creation only happens if DB is empty, and existing projects return info. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences efficiently convey purpose, conditional behavior, and parameter usage. No redundancy, front-loaded information.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple parameters, no output schema, and good annotations, the description covers both scenarios comprehensively. No missing information for an agent to decide or invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. Description restates that project_name is only used if DB empty, but adds no new semantics beyond schema. Adequate but no extra value.

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?

Description clearly states the tool initializes a tracker for a project, with explicit conditional behavior: creates if DB empty, returns info if exists. Distinguishes from siblings like project_create and project_get by handling initialization logic.

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?

Provides clear context on when to use (initializing a tracker). Does not explicitly exclude alternative tools, but the conditional behavior makes usage clear. Among siblings, it's distinct from tracker_dashboard, etc.

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

tracker_nextA

Read-onlyIdempotent

What to work on next: one recommended task with the reason, its next unfinished subtask, alternatives, and — when nothing is actionable — what to unblock. Call it when resuming work; cheaper than tracker_dashboard.

ParametersJSON Schema

Name	Required	Description
`branch`	No	Git branch filter: "current" = active branch, omit = all.
`project_id`	No	Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database.
`assigned_to`	No	Only consider tasks assigned to this person

TDQS

A4.3/5.0

Behavior4/5

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

The description adds behavioral context beyond the readOnly/idempotent annotations: it returns exactly one recommendation, includes reasoning and alternatives, and defines an unblock path when nothing is actionable. It also adds a performance/cost signal ('cheaper than tracker_dashboard').

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences deliver purpose, output composition, usage timing, and a comparison to the sibling. The most important information is front-loaded and there is no redundancy.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only recommendation tool with full parameter schema coverage and safety annotations, the description covers everything an agent needs: output structure, when to call it, and behavior when there is nothing actionable. No output schema exists, but the prose specifies the result shape clearly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter is already well described in the input schema. The tool description adds no parameter-level detail, but that is acceptable because the schema already carries the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that tracker_next produces one recommended task with a reason, its next unfinished subtask, alternatives, and an unblock suggestion. This distinguishes it from list/search tools like tracker_dashboard and tracker_search because it is specifically a recommendation, not a general index.

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?

It explicitly says 'Call it when resuming work' and positions it as cheaper than tracker_dashboard, giving the agent a clear condition and alternative. It doesn't exhaustively enumerate when not to use it, but the context is sufficient for routing.

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

tracker_searchA

Read-onlyIdempotent

Search projects, epics, tasks and notes by keyword. Returns categorized previews — use task_get or note_list for full text.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Max results per entity type
`query`	Yes	Search keywords
`branch`	No	Git branch filter: "current" = active branch, "" = branch-agnostic only, omit = all.
`project_id`	No	Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database.
`entity_types`	No	Limit search to specific entity types (omit for all)
`include_archived`	No	Include archived epics and their tasks.

TDQS

A4.2/5.0

Behavior4/5

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

With annotations already marking this as read-only, idempotent, and non-destructive, the description adds useful behavioral context beyond those annotations: it returns categorized previews and directs the agent away from full-text retrieval. This is meaningful behavioral disclosure without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core purpose is front-loaded, the output type is stated, and the pointer to full-text tools earns its place. Every sentence carries useful information.

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?

Given six parameters, full schema coverage, and no output schema, the description is reasonably complete: it explains the tool's role, the preview nature of results, and where to go for full text. A little more detail about the exact response shape would be helpful, but the current text plus schema is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented. The description itself adds only the general notion of searching 'by keyword' and preview output, which aligns with query but does not materially enhance the schema's parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Search'), the resources ('projects, epics, tasks and notes'), and the keyword-based scope. It also distinguishes itself from retrieval tools by noting it returns 'categorized previews' rather than full text, so an agent can tell it apart from task_get and note_list.

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 provides clear usage context: use this tool for keyword search and previews, and switch to task_get or note_list when full text is needed. It does not explicitly enumerate exclusions or mention sibling note_search, but the guidance is sufficiently clear for typical search-versus-retrieval decisions.

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

tracker_session_diffA

Read-onlyIdempotent

What changed since a timestamp: counts by action and entity, plus the notable changes. Call it at the start of a session to catch up.

ParametersJSON Schema

Name	Required	Description	Default
`since`	Yes	ISO 8601 datetime — show changes after this time (e.g. "2026-02-21T15:00:00")

TDQS

A4/5.0

Behavior4/5

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

Annotations already indicate readOnly, idempotent, non-destructive behavior, so the description's job is to add behavioral context. It does this by describing the output nature: counts by action and entity plus notable changes. It does not contradict annotations and adds useful expectations beyond the structured metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the core purpose, and includes a practical usage pointer. Every sentence earns its place with no wasted words.

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?

For a simple read-only tool with one parameter and no output schema, the description is sufficiently complete: it states what is returned, when to call it, and the time-based input. It could optionally mention the timezone or that no nested data is returned, but neither is essential for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes the 'since' parameter with ISO 8601 format and an example, so description-level parameter detail is largely redundant. The description reinforces the meaning of 'since a timestamp,' but adds little beyond the schema, earning the baseline score for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports what changed since a timestamp, including counts by action and entity plus notable changes. It is understandable and consistent with the tool name, though it lacks an explicit verb like 'retrieve' and does not name a sibling to differentiate from.

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 gives explicit guidance: 'Call it at the start of a session to catch up.' This provides a clear when-to-use scenario, though it does not mention when not to use it or compare it to similar tools like activity_log or tracker_dashboard.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

12 tool updatesv1.16.0Sep 9, 2026

Changedactivity_log1 field changed

changedInput schema / properties / project_id / description

Previous value: -"Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database."New value: +"Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database."

Changednote_list1 field changed

changedInput schema / properties / project_id / description

Previous value: -"Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database."New value: +"Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database."

Changedsubtask_update1 field changed

changedInput schema / properties / force / description

Previous value: -"Proceed despite unmet prerequisites. Only when a human decided the blocker no longer applies — never on your own initiative. Logged."New value: +"Proceed despite unmet prerequisites. Only when a human says the blocker no longer applies, never on your own initiative. Logged."

Changedtask_batch_update1 field changed

changedInput schema / properties / force / description

Previous value: -"Proceed despite unmet prerequisites. Only when a human decided the blocker no longer applies — never on your own initiative. Logged."New value: +"Proceed despite unmet prerequisites. Only when a human says the blocker no longer applies, never on your own initiative. Logged."

Changedtask_list3 fields changed

changedInput schema / properties / project_id / description

Previous value: -"Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database."New value: +"Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database."

removedInput schema / properties / sort_by / default
```
Removed value: -"priority"
```

changedInput schema / properties / sort_by / description

Previous value: -"priority (critical first), created (newest first), due_date (earliest first), status (actionable first), manual (the order set by task_reorder)"New value: +"Omit to follow the arrangement set by task_reorder, falling back to priority. priority (critical first), created (newest), due_date (earliest), status (actionable first), manual."

Changedtask_update1 field changed

changedInput schema / properties / force / description

Previous value: -"Proceed despite unmet prerequisites. Only when a human decided the blocker no longer applies — never on your own initiative. Logged."New value: +"Proceed despite unmet prerequisites. Only when a human says the blocker no longer applies, never on your own initiative. Logged."

Changedtemplate_create1 field changed

changedInput schema / properties / tasks / description

Previous value: -"Task definitions. Use {variable} for placeholders."New value: +"The tasks this template creates."

Changedtemplate_list1 field changed

addedInput schema / properties / include_tasks

Added value: +{
+  "description": "Return each template's task definitions, not just a count.",
+  "type": "boolean"
+}

Addedtemplate_update

Changedtracker_dashboard1 field changed

changedInput schema / properties / project_id / description

Previous value: -"Project ID. Omit if the database holds one project, or if SAGA_PROJECT is set. With several projects and neither, the first is used and the rest are listed under other_projects."New value: +"Project ID. Omit for a single-project database or when SAGA_PROJECT is set. Otherwise the first is used and the rest listed under other_projects."

Changedtracker_next1 field changed

changedInput schema / properties / project_id / description

Previous value: -"Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database."New value: +"Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database."

Changedtracker_search1 field changed

changedInput schema / properties / project_id / description

Previous value: -"Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database."New value: +"Scope to one project. Defaults to SAGA_PROJECT if set, else the whole database."

5 tool updatesv1.14.0Sep 8, 2026

Changedtask_list2 fields changed

changedInput schema / properties / sort_by / description

Previous value: -"Sort order: priority (critical first), created (newest first), due_date (earliest first), status (actionable first)"New value: +"priority (critical first), created (newest first), due_date (earliest first), status (actionable first), manual (the order set by task_reorder)"

changedInput schema / properties / sort_by / enum

Previous value: -[
-  "priority",
-  "created",
-  "due_date",
-  "status"
-]New value: +[
+  "priority",
+  "created",
+  "due_date",
+  "status",
+  "manual"
+]

Addedtask_reorder

Changedtask_update1 field changed

addedInput schema / properties / sort_order / description

Added value: +"Manual position within the epic; lower sorts first. Use task_reorder instead of setting this by hand."

Changedtemplate_create1 field changed
- removedInput schema / properties / description / description
```
Removed value: -"Template description"
```
Addedtracker_next

22 tool updatesv1.10.0Sep 6, 2026

Changedactivity_log1 field changed

addedInput schema / properties / project_id

Added value: +{
+  "description": "Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database.",
+  "type": "integer"
+}

Addedcomment_delete

Changedcomment_list1 field changed

addedInput schema / properties / include_deleted

Added value: +{
+  "default": false,
+  "description": "Include comments that were removed (soft-deleted). Off by default.",
+  "type": "boolean"
+}

Addedcomment_restore
Addedepic_archive

Changedepic_create1 field changed

changedInput schema / properties / branch / description

Previous value: -"Git branch this epic is scoped to. Pass \"current\" to auto-detect from the repo. Omit or pass empty string for a branch-agnostic (global) epic."New value: +"Branch to scope this epic to: \"current\" = active branch, omit/\"\" = branch-agnostic."

Changedepic_list2 fields changed

changedInput schema / properties / branch / description

Previous value: -"Filter by git branch. Pass \"current\" to auto-detect; pass empty string to list only branch-agnostic epics. Omit to list all."New value: +"Git branch filter: \"current\" = active branch, \"\" = branch-agnostic only, omit = all."

addedInput schema / properties / include_archived

Added value: +{
+  "default": false,
+  "description": "Include archived epics and their tasks.",
+  "type": "boolean"
+}

Changedepic_update1 field changed

changedInput schema / properties / branch / description

Previous value: -"Git branch this epic is scoped to. Pass \"current\" to auto-detect; pass empty string to clear (branch-agnostic)."New value: +"Branch to scope this epic to: \"current\" = active branch, \"\" = clear."

Changednote_list1 field changed

addedInput schema / properties / project_id

Added value: +{
+  "description": "Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database.",
+  "type": "integer"
+}

Changedsubtask_create6 fields changed

addedInput schema / properties / depends_on

Added value: +{
+  "description": "Siblings each new subtask waits on",
+  "items": {
+    "type": "integer"
+  },
+  "type": "array"
+}

changedInput schema / properties / task_id / description

Previous value: -"Parent task ID"New value: +"Parent task"

addedInput schema / properties / titles / description

Added value: +"Subtask titles, one per array item — e.g. [\"Write it\", \"Test it\"]. Always an array, even for a single subtask."

addedInput schema / properties / titles / items
```
Added value: +{
+  "type": "string"
+}
```

removedInput schema / properties / titles / oneOf

Removed value: -[
-  {
-    "description": "Single subtask title",
-    "type": "string"
-  },
-  {
-    "description": "Multiple subtask titles",
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  }
-]

addedInput schema / properties / titles / type
```
Added value: +"array"
```

Changedsubtask_delete4 fields changed

addedInput schema / properties / ids / description

Added value: +"Subtask IDs to delete — e.g. [4, 7]. Always an array, even for one."

addedInput schema / properties / ids / items
```
Added value: +{
+  "type": "integer"
+}
```

removedInput schema / properties / ids / oneOf

Removed value: -[
-  {
-    "description": "Single subtask ID",
-    "type": "integer"
-  },
-  {
-    "description": "Multiple subtask IDs",
-    "items": {
-      "type": "integer"
-    },
-    "type": "array"
-  }
-]

addedInput schema / properties / ids / type
```
Added value: +"array"
```

Addedsubtask_reorder

Changedsubtask_update4 fields changed

addedInput schema / properties / blocks

Added value: +{
+  "description": "Siblings that wait on this one — inverse of depends_on",
+  "items": {
+    "type": "integer"
+  },
+  "type": "array"
+}

addedInput schema / properties / depends_on

Added value: +{
+  "description": "Siblings this one waits on (replaces the set)",
+  "items": {
+    "type": "integer"
+  },
+  "type": "array"
+}

addedInput schema / properties / force

Added value: +{
+  "default": false,
+  "description": "Proceed despite unmet prerequisites. Only when a human decided the blocker no longer applies — never on your own initiative. Logged.",
+  "type": "boolean"
+}

removedInput schema / properties / id / description
```
Removed value: -"Subtask ID"
```

Changedtask_batch_update1 field changed

addedInput schema / properties / force

Added value: +{
+  "default": false,
+  "description": "Proceed despite unmet prerequisites. Only when a human decided the blocker no longer applies — never on your own initiative. Logged.",
+  "type": "boolean"
+}

Changedtask_create3 fields changed
- removedInput schema / properties / source_ref / properties / file / description
```
Removed value: -"File path"
```
- removedInput schema / properties / source_ref / properties / line_end / description
```
Removed value: -"End line number"
```
- removedInput schema / properties / source_ref / properties / line_start / description
```
Removed value: -"Start line number"
```
Addedtask_delete

Changedtask_list4 fields changed

changedInput schema / properties / branch / description

Previous value: -"Filter by the git branch of the task's epic. Pass \"current\" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to list all."New value: +"Git branch filter: \"current\" = active branch, \"\" = branch-agnostic only, omit = all."

addedInput schema / properties / include_archived

Added value: +{
+  "default": false,
+  "description": "Include archived epics and their tasks.",
+  "type": "boolean"
+}

addedInput schema / properties / include_deleted

Added value: +{
+  "default": false,
+  "description": "Include removed tasks.",
+  "type": "boolean"
+}

addedInput schema / properties / project_id

Added value: +{
+  "description": "Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database.",
+  "type": "integer"
+}

Addedtask_lock_description
Addedtask_restore

Changedtask_update4 fields changed

addedInput schema / properties / force

Added value: +{
+  "default": false,
+  "description": "Proceed despite unmet prerequisites. Only when a human decided the blocker no longer applies — never on your own initiative. Logged.",
+  "type": "boolean"
+}

removedInput schema / properties / source_ref / properties / file / description
```
Removed value: -"File path"
```
removedInput schema / properties / source_ref / properties / line_end / description
```
Removed value: -"End line number"
```
removedInput schema / properties / source_ref / properties / line_start / description
```
Removed value: -"Start line number"
```

Changedtracker_dashboard3 fields changed

changedInput schema / properties / branch / description

Previous value: -"Scope to a git branch. Pass \"current\" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to include everything."New value: +"Scope to a git branch: \"current\" = active branch, \"\" = branch-agnostic only, omit = all."

addedInput schema / properties / include_archived

Added value: +{
+  "default": false,
+  "description": "Include archived epics and their tasks.",
+  "type": "boolean"
+}

changedInput schema / properties / project_id / description

Previous value: -"Project ID (omit if only one project exists)"New value: +"Project ID. Omit if the database holds one project, or if SAGA_PROJECT is set. With several projects and neither, the first is used and the rest are listed under other_projects."

Changedtracker_search3 fields changed

changedInput schema / properties / branch / description

Previous value: -"Filter epic/task results by git branch. Pass \"current\" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to include all."New value: +"Git branch filter: \"current\" = active branch, \"\" = branch-agnostic only, omit = all."

addedInput schema / properties / include_archived

Added value: +{
+  "default": false,
+  "description": "Include archived epics and their tasks.",
+  "type": "boolean"
+}

addedInput schema / properties / project_id

Added value: +{
+  "description": "Scope to one project. Needed when a single database holds several projects; defaults to the SAGA_PROJECT env var if set, otherwise the whole database.",
+  "type": "integer"
+}

6 tool updatesv1.5.5May 12, 2026

Changedepic_create1 field changed

addedInput schema / properties / branch

Added value: +{
+  "description": "Git branch this epic is scoped to. Pass \"current\" to auto-detect from the repo. Omit or pass empty string for a branch-agnostic (global) epic.",
+  "type": "string"
+}

Changedepic_list1 field changed

addedInput schema / properties / branch

Added value: +{
+  "description": "Filter by git branch. Pass \"current\" to auto-detect; pass empty string to list only branch-agnostic epics. Omit to list all.",
+  "type": "string"
+}

Changedepic_update1 field changed

addedInput schema / properties / branch

Added value: +{
+  "description": "Git branch this epic is scoped to. Pass \"current\" to auto-detect; pass empty string to clear (branch-agnostic).",
+  "type": "string"
+}

Changedtask_list1 field changed

addedInput schema / properties / branch

Added value: +{
+  "description": "Filter by the git branch of the task's epic. Pass \"current\" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to list all.",
+  "type": "string"
+}

Changedtracker_dashboard1 field changed

addedInput schema / properties / branch

Added value: +{
+  "description": "Scope to a git branch. Pass \"current\" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to include everything.",
+  "type": "string"
+}

Changedtracker_search1 field changed

addedInput schema / properties / branch

Added value: +{
+  "description": "Filter epic/task results by git branch. Pass \"current\" to auto-detect; pass empty string to restrict to branch-agnostic epics. Omit to include all.",
+  "type": "string"
+}

31 tool updatesv1.5.3Mar 16, 2026
- First observedactivity_log
- First observedcomment_add
- First observedcomment_list
- First observedepic_create
- First observedepic_list
- First observedepic_update
- First observednote_delete
- First observednote_list
- First observednote_save
- First observednote_search
- First observedproject_create
- First observedproject_list
- First observedproject_update
- First observedsubtask_create
- First observedsubtask_delete
- First observedsubtask_update
- First observedtask_batch_update
- First observedtask_create
- First observedtask_get
- First observedtask_list
- First observedtask_update
- First observedtemplate_apply
- First observedtemplate_create
- First observedtemplate_delete
- First observedtemplate_list
- First observedtracker_dashboard
- First observedtracker_export
- First observedtracker_import
- First observedtracker_init
- First observedtracker_search
- First observedtracker_session_diff

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-09-09 22:40 across 41 tools

Disambiguation3/5

Most tools have distinct resource-action pairs (task_create vs epic_create), but some overlap: tracker_init initializes a project while project_create creates one; tracker_dashboard, tracker_session_diff, and activity_log all provide overview/activity info, though with different scopes. Also task_get vs task_list vs tracker_search could create some selection ambiguity.

Naming Consistency4/5

Most tools follow a consistent noun_verb pattern (e.g., task_create, task_update, epic_list, note_save). Exceptions like note_save (verb_noun) and activity_log (noun_noun) break the pattern, and tracker_* and template_* prefixes are mixed but still readable.

Tool Count2/5

41 tools is excessive for a project management server, even with comprehensive functionality. Many tools could be consolidated (e.g., note_save could be split into create/update, or tracker_export/import are edge-case features). This is well beyond the typical 3-15 tool sweet spot and creates cognitive load.

Completeness5/5

The tool surface is remarkably complete: full lifecycle for projects, epics, tasks, subtasks, notes, comments, and templates. Includes reordering, soft-delete with restore, batch operations, search, dashboard, diff, and import/export. There are no obvious dead ends; every entity has create/read/update/delete plus additional utilities.

Maintenance

ActivityMaintained

ResponsivenessResponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
StateyOAuth
ai.statey
An agent-native database over MCP: shared, validated, structured records in every AI chat.
Databases Knowledge & Memory
2
Kangram
app.kangram
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Project Management
1
Tasg
app.tasg
Work management where AI agents are first-class members: tasks, projects, memory over hosted MCP
Project Management Autonomous Agents Knowledge & Memory
1

Related MCP Servers

task-orchestrator
Agent Orchestration Project Management Autonomous Agents
jpicklyk
A
license
Not graded
quality
A
maintenance
Server-enforced workflow discipline for AI agents. An MCP server providing persistent work items, dependency graphs, quality gates, and actor attribution. Schemas define what agents must produce — the server blocks the call if they don't. Works with any MCP-compatible client.
Updated a month ago (2026-08-04 20:40 UTC)
206
MIT
Project Tracker MCP Server
Project Management Developer Tools
spranab
F
license
B
quality
D
maintenance
MCP server for managing hierarchical project tracking with PostgreSQL. Enables AI agents to create, read, update, and delete projects, epics, stories, summaries, status updates, context, and issues.
Updated a year ago (2025-10-02 06:14 UTC)
40
2
-
Lific
Project Management Developer Tools Knowledge & Memory
VoidNullable
A
license
B
quality
A
maintenance
Self-hosted issue tracker built for agent-driven development. One binary, SQLite storage, MCP-native, with a web UI, REST API, and CLI for the humans.
Updated 2 days ago (2026-09-12 01:26 UTC)
27
50
Apache 2.0
Flow
Project Management App Automation
joelborch
A
license
Not graded
quality
B
maintenance
Agent-first project management MCP server that enables AI agents to manage tasks, spaces, lists, boards, subtasks, comments, and automations via natural language, with full audit trail and real-time sync.
Updated 4 days ago (2026-09-09 11:57 UTC)
6,899 npm
MIT

Appeared in Searches

A production-ready Task Management MCP server for AI agents and autonomous workflows

saga-mcp

Install

Settings

Your first session

What you get

Asking what to do next

Ordering and dependencies

Keeping agents on the rails

Comments as a decision trail

Templates

Getting old work out of the way

Forgiving input

One database, many projects

Web UI

Token cost

Tool reference

Getting started

Projects

Epics

Tasks

Subtasks

Comments

Templates

Notes

Search, history and transfer

How it works

Note types

Activity log

Privacy

Development

Releasing

Support

Related projects

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches