Skip to main content
Glama
spranab

Saga MCP

by spranab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

task_list

Read-onlyIdempotent

Retrieve project tasks across all epics with filters for status, priority, assignee, tag, project, or git branch. Each row includes subtask and dependency counts, showing compact details and truncated descriptions.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tagNoFilter by tag
limitNoMax results
branchNoGit branch filter: "current" = active branch, "" = branch-agnostic only, omit = all.
statusNo
epic_idNoFilter by epic (omit for all tasks)
sort_byNoOmit to follow the arrangement set by task_reorder, falling back to priority. priority (critical first), created (newest), due_date (earliest), status (actionable first), manual.
priorityNo
project_idNoScope to one project. Defaults to SAGA_PROJECT if set, else the whole database.
assigned_toNoFilter by assignee
include_deletedNoInclude removed tasks.
include_archivedNoInclude archived epics and their tasks.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.16.0
    • 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."
  2. Changed2 schema fields changedv1.14.0
    • 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"
+]
  3. Changed4 schema fields changedv1.10.0
    • 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"
+}
  4. Changed1 schema field changedv1.5.5
    • 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"
+}
  5. First observedv1.5.3

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.

Deploy Server

Other Tools