Allows starting GitHub Copilot CLI sessions linked to tasks for AI-assisted development.
Opens new iTerm2 tabs to start or resume AI agent sessions for tasks.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tasq add a task: review PR #42"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local-first task manager, exposed as a CLI, an interactive TUI, and a local MCP server, backed by a single SQLite file. Built with Python, uv, Typer, Textual, and the MCP SDK.
See spec.md for the original design and rationale.
tasq keeps your work in one SQLite file on your machine — no account, no server,
no sync — and lets you drive it three ways over the same engine: type commands
(tasq …), scroll an interactive board (tasq ui), or let an AI assistant manage
tasks through the built-in MCP server. Anything you do one way is immediately
visible in the others.
The mental model. A task has a title, a status, a priority (P1–P5), an optional t-shirt size (XS–XL, used for effort estimates), optional scheduled (start) and due dates, a markdown description, and any number of labels. Tasks can be grouped under a project and broken into one level of sub-tasks. Every status change is recorded as an auditable history — you can always see when and why a task moved, not just where it is now.
What you can do with it:
Capture & organise — add tasks with priority, size, dates, labels, and rich descriptions; group them by project; break them into sub-tasks.
Track a lifecycle — move tasks through waiting → in-progress → blocked → done/cancelled, each transition logged with an optional comment.
See what's next — an agenda (overdue + today + upcoming) with effort estimates, and a proposed day-by-day plan that packs open work into your daily focus budget over working days (weekends skipped) — a suggestion, never written back to a task. Export the plan as an HTML report.
Find things — fuzzy search across titles/descriptions (typos are fine), and a references view that pulls URLs (PRs, JIRAs, docs) out of descriptions so you can jump straight to them.
Work interactively — a full-screen board (tasq ui) to scroll, quick-edit
priority/size/status, create/schedule/delete tasks, open references, and view
the plan — all with the keyboard.
Hand off to (and resume) AI agents — link a task to the AI coding session you worked on it in (agent, directory, session id, launcher/profile), then resume or start that session in a new iTerm2 tab — a fresh session is primed with a task briefing so the agent self-manages via tasq. Configurable launchers and project directories make this a one-key action.
Be legible to an AI — the MCP server exposes every capability as a tool, and labels carry human-written descriptions so an assistant acts on intent, not guesswork.
Nothing leaves your machine: it's a single local SQLite file (WAL + FTS5), and the CLI, TUI, and MCP server are thin adapters over one shared core.
Related MCP server: taskdog-mcp
Install with uv:
uv sync
uv run tasq --help # or symlink the ./tasq wrapper onto your PATHSee it populated in seconds — seed a throwaway demo database (it never touches your real tasks) and open the board:
uv run tasq demo --ui # seeds a demo.db and opens `tasq ui`
# …or explore piece by piece:
tasq demo # prints the exact commands to try (agenda, plan, …)Start using it for real:
tasq add "Write the launch post" -p blog --priority 2 --due 2026-08-20
tasq ui # your board (1-5 = priority · n = new · ! = flag · a = agent)Wire it into your AI assistant — register the MCP server (see Claude Code / GitHub Copilot below) and your agent can capture, plan, and flag tasks just like you do. Then follow the AI workflow walkthrough for the full loop: start a task in an agent → it links its session and pings you when it needs a decision → you answer → resume where it left off.
uv sync # install dependencies
uv run tasq --help # the `tasq` (and short `tq`) commandThe database lives at $XDG_DATA_HOME/tasq/tasks.db by default. Override with
--db PATH or the TASQ_DB environment variable.
# Capture
tasq add "Write the spec" -p acme --priority 2 --size M --due 2026-07-25 \
-l writing --desc "See [design](https://figma.com/f/abc) and https://github.com/acme/repo"
# Missing dates are guessed: start = next working day, due = a few business days later
tasq add "Follow up with infra" # e.g. start 2026-07-31 · due 2026-08-07
tasq add "Someday idea" --no-guess-dates # leave both dates unset
# See what's next
tasq agenda --days 5 # overdue + today + upcoming, with effort estimates
tasq today
tasq overdue
# Get a proposed day-by-day schedule — a suggestion, never written back to tasks
tasq plan # packs open tasks into 5h/day over 5 working days
tasq plan --days 10 --hours 6 # 10 working days at 6 focus-hours/day
tasq plan --weekends # include Sat/Sun (excluded by default)
tasq plan -o html --browser # write an HTML report and open it in the browser
tasq plan -o html --out plan.html # …or just write it to a specific file
tasq plan -p Work -p IGM # limit planning to certain projects
tasq plan -L personal # keep private (labelled) tasks out of the plan
# Interactive board: scroll the task list and quick-edit with the keyboard
tasq ui # 1-5 = priority · shift+←/→ = size · s/b/d = start/block/done
# n = new task · t = set start date · o = open refs in browser
# / = fuzzy find · ! = flag for attention · p = project filter · v = plan view
# a = start in an AI agent · x = delete
# L = references view (u = unique · / = search · b = open as HTML)
# r = reload · R = resume in iTerm
# enter = edit (shows clickable refs + AI session, has Delete)
# ⟳ = linked AI session (resumable) · ⚠ = needs attention (rings a bell)
# auto-refreshes every 5s (configurable), so agent/CLI changes just appear
# Open a task's reference URLs (PRs, JIRAs, …) in the browser
tasq open 2 # opens every URL extracted from task #2's description
tasq refs open 5 # …or open a single extracted reference by its ref-id
# Link a task to the AI session you're working in, so it can be resumed later
tasq link 2 -a claude-code -d . -s <session-id> -c claude-work
# -c is the command/alias you launched with (selects a profile)
tasq unlink 2 # drop the session link
# Start a task in an AI agent — new iTerm2 tab, primed with a task briefing (macOS)
tasq work 2 # prompts for a project dir + launcher, opens a briefed session
tasq work 2 -D igm # start in the 'igm' project dir (its default launcher)
tasq work 2 -D igm -l claude-work # …and pick one of that dir's allowed launchers
tasq work 2 --resume # resume a session instead of a new briefed one
tasq work 2 -D igm --print # print the launch command instead of opening iTerm
# Resume a linked session — opens a new iTerm2 tab, cds in, and runs the agent (macOS)
tasq resume 2 # e.g. `cd <dir> && claude-work --resume <session-id>`
tasq resume 2 --print # just print the command (no iTerm), for other terminals
# Break a task into sub-tasks (one level deep; they show in list/agenda too)
tasq add "Write migration" --parent 1 --priority 1
tasq subtasks 1 # list a task's sub-tasks
tasq edit 3 --no-parent # promote a sub-task back to top-level
tasq list --top-level # hide sub-tasks from the flat list
# Flag a task as awaiting your attention (an AI agent can do this via MCP)
tasq flag 3 -m "which auth provider — okta or auth0?" # stands out + rings a bell in the UI
tasq list --attention # everything currently flagged
tasq unflag 3 # clear it once you've answered
# Move it through its lifecycle (comment optional, recorded either way)
tasq start 1 -m "picking this up"
tasq block 1 -m "waiting on backend"
tasq done 1
tasq history 1
# Find things (fuzzy — typos are fine)
tasq search "lgin bug"
tasq refs # every extracted URL (PRs, JIRAs), newest first
tasq refs --unique # collapse duplicate URLs → one row per link + task count
tasq refs -o html --browser # write an HTML report of the references and open it
tasq refs github # …or fuzzy-search them
tasq refs open 2 # open a matched URL
# Projects & labels (labels carry AI-facing descriptions)
tasq project add acme -l globex-corp
tasq label describe deep-work --desc "Requires 2h+ focus; schedule in the morning"
tasq label list
# Pull work in from external sources (PRs to review, JIRAs, emails), deduplicated
tasq fetch reviews --org acme # PRs awaiting your review (via `gh`) → tasks, deduped
tasq fetch reviews --user octocat --print # …or just print the ingest JSON
your-fetcher | tasq ingest --source jira # any fetcher: upsert JSON by (source, external_id)
tasq list --source github-reviews # what's been synced
# re-running never duplicates; see docs/ingestion.md for the item schema + example fetchers
# Machine-readable output for any query command
tasq list --status waiting,blocked --jsonPlanning and effort estimates are tunable via an optional TOML file at
$XDG_CONFIG_HOME/tasq/config.toml (override with TASQ_CONFIG). Everything has a
default, so the file is optional. TASQ_DAILY_HOURS overrides the daily budget for
a single run, and tasq plan --hours N overrides it per-invocation.
[planning]
daily_hours = 5 # focus hours/day for `plan`; the rest is meetings/overhead
include_weekends = false # plan Mon–Fri only (override per-run with --weekends)
projects = [] # only plan these projects (empty = all); overridable with -p
labels = [] # only plan tasks carrying one of these labels
exclude_labels = ["personal"] # keep private work out of the plan (override with -L)
[effort]
unsized_hours = 2 # assumed effort for a task with no size
[effort.size_hours] # hours per t-shirt size (drives estimates and `plan`)
XS = 0.5
S = 1
M = 2
L = 4
XL = 8
[add]
guess_dates = true # fill missing start/due when adding (override with --no-guess-dates)
due_business_days = 5 # due lands this many working days after the start date
[ui]
refresh_seconds = 5 # how often `tasq ui` polls for changes (0 disables auto-refresh)
[agents.launchers] # commands/aliases for `tasq work` (each alias can be a profile)
claude = "claude-code"
claude-work = "claude-code"
copilot = "github-copilot-cli"
# Big-project directories agents can be started in (one table per project).
# `launchers` (defaults to all) restricts what's allowed there; `default` (defaults
# to the first) is preselected. `name` defaults to the path's basename.
[[agents.project_dirs]]
name = "igm"
path = "/Users/me/IGT/Azure/repos/igm"
launchers = ["copilot", "claude-work"]
default = "copilot"
# Customise the briefing that primes a fresh `tasq work` session. Placeholders
# $id, $title, $description are filled in (use ${id} next to letters). Optional —
# omit to use the built-in briefing.
[agents]
prompt_template = """
Work on tasq task #$id: $title.
$description
Link this session to task #$id in tasq, mark it in_progress, ask me for context,
and record any relevant PR / JIRA / repo URLs as you go.
"""Run the server over stdio:
tasq serveRegister it with an MCP client (e.g. Claude Desktop):
{
"mcpServers": {
"tasq": { "command": "uvx", "args": ["tasq", "serve"] }
}
}The examples below use
uvx tasq serve, which works once the package is published. To run from a local checkout instead, useuvwith--directory, e.g."command": "uv", "args": ["run", "--directory", "/path/to/tasq", "tasq", "serve"]. Point at a specific database with theTASQ_DBenv var if you don't want the default.
Add it from the terminal (project-scoped):
claude mcp add tasq -- uvx tasq serve…or commit a .mcp.json at the repository root so the whole team gets it:
{
"mcpServers": {
"tasq": {
"command": "uvx",
"args": ["tasq", "serve"],
"env": { "TASQ_DB": "${HOME}/.local/share/tasq/tasks.db" }
}
}
}Copilot's agent mode reads MCP servers from .vscode/mcp.json (note the
top-level servers key and the type field):
{
"servers": {
"tasq": {
"type": "stdio",
"command": "uvx",
"args": ["tasq", "serve"],
"env": { "TASQ_DB": "${env:HOME}/.local/share/tasq/tasks.db" }
}
}
}Then open the Copilot Chat Agent view and enable the tasq tools. (User-level
config lives under "mcp": { "servers": { … } } in VS Code settings.json.)
It exposes tools (add_task, edit_task, get_task, list_tasks,
search_tasks, search_references, transition_task, flag_attention,
clear_attention, link_session, unlink_session, ingest, agenda, plan,
project/label management) and resources
(task://{id}, agenda://today, agenda://upcoming, labels://). Labels are
surfaced with their descriptions, so an assistant knows what each means and
when to apply it. The agent has full read/write access.
Linking a session: link_session(task_id, agent, directory, session_id, launcher)
records which AI CLI worked on a task, where, under which session id, and with
which command/alias (so a resume can pick the right profile). Ask the agent to
"link this session to task #N" and it stores the details for later resumption.
Asking for your attention: when an agent needs a decision or input, it calls
flag_attention(task_id, note). The task then stands out (a ⚠ row) and rings a
bell in your open board — which auto-refreshes — so you notice without watching the
terminal. clear_attention(task_id) removes the flag once you've responded.
AI workflow walkthrough — the full loop: start a task in an agent, get pinged when it needs a decision, and resume where it left off.
Ingesting external tasks — pull in PRs/JIRAs/emails as deduplicated tasks (the item schema, upsert semantics, and example fetchers).
spec.md — the original design and rationale (historical: it predates the TUI and the AI-session features, which have since shipped).
Try tasq demo for a populated database to explore hands-on.
The CLI and MCP server are thin adapters over a shared core:
tasq.cli ─┐
├─▶ tasq.services.Core ─▶ tasq.repository ─▶ SQLite
tasq.mcp ─┘ (use cases) (typed rows)models.py — enums + frozen, fully-typed dataclasses (the domain objects).
repository.py — the only place that touches sqlite3 rows.
services.py — use cases, transactions, and domain rules.
references.py / search.py — URL extraction and fuzzy (FTS5 + rapidfuzz) search.
serialize.py — one shared dict shape for CLI --json and MCP output.
uv run pytest # tests
uv run mypy # strict type checking
uv run ruff check . # lint
uv run ruff format . # formatCreate a project. Project labels describe the project (e.g. the company).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| labels | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Create a project' and adds a note about labels being descriptive. It does not disclose side effects, error conditions, idempotency, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action and followed by a clarifying note on labels. There is no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation, the description is minimal. It lacks information about uniqueness, required fields (though the schema covers this), or behavioral nuances. The presence of an output schema helps but does not fully compensate for the missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains the 'labels' parameter with an example ('the company'), leaving 'name' and 'description' unexplained beyond their property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a project,' which clearly identifies the operation and resource. It is distinct from sibling tools like add_task, list_projects, and archive_project, though it does not explicitly mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states the action without contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a task. priority is 1 (highest)–5; size is XS/S/M/L/XL;
dates are ISO 'YYYY-MM-DD'; project is a project name (created if new).
Pass parent_id to make this a sub-task (nesting is limited to one level).
When guess_dates is true (default), a missing start date defaults to the
next working day and a missing due date to a few business days later; pass
false to leave dates unset.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| title | Yes | ||
| labels | No | ||
| project | No | ||
| due_date | No | ||
| priority | No | ||
| parent_id | No | ||
| description | No | ||
| guess_dates | No | ||
| scheduled_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It discloses multiple non-obvious behaviors: priority range, size enums, date format, project auto-creation, nesting limit, and the guess_dates default behavior. This goes well beyond what the schema alone provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise despite covering many parameters. Each sentence provides valuable information, with code-formatted value examples for quick scanning. It is appropriately structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 10 parameters and an output schema, the description covers important side effects and defaults. It does not detail the behavior of labels, description, or scheduled_date, but these are straightforward optional fields. The description adequately addresses the tool's main behaviors and edge cases like guess_dates and project creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds semantics for priority, size, date formats, project auto-creation, parent_id nesting, and guess_dates. However, it does not explain labels, description, or scheduled_date beyond their schema names, leaving some parameters less clear. Still, the major fields are well covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a task,' which is a specific verb and resource. It clearly distinguishes this from sibling tools like edit_task, list_tasks, and get_task, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage by explaining parameter behaviors such as project auto-creation and nesting limits. While it doesn't explicitly state when to use this tool over alternatives, the creation focus is obvious and the details on defaults and constraints offer practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overdue, today, upcoming (next N days), and in-progress/blocked tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must disclose behavioral traits. It lists categories and implies retrieval of tasks but doesn't state whether it's read-only, how results are sorted/grouped, or any side effects. This lack of behavioral detail is a significant gap for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, but it's a sentence fragment without a verb, which reduces clarity. It could benefit from a verb and more structured phrasing, though it has no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, return values are covered, but the description doesn't clarify the tool's core function or usage context. It also doesn't mention how categories are combined or whether tasks can appear in multiple categories, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'days' parameter via 'upcoming (next N days)', indicating that days controls the horizon for upcoming tasks. Since schema coverage is 0%, this compensation is valuable, though it doesn't explicitly name the parameter or mention its default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description lists categories (overdue, today, upcoming, in-progress/blocked) but lacks a verb or explicit resource, making it a noun phrase rather than a clear statement of what the tool does. It doesn't distinguish from sibling tools like list_tasks, which might also return task lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_tasks or search_tasks. There are no exclusions, alternatives, or contextual hints, leaving the agent to guess its appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a project (kept, not deleted).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clarifies that archiving is non-destructive ('kept, not deleted'), which is a key behavioral trait. However, it does not disclose other important aspects such as reversibility or effects on associated tasks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and adds a clarifying note. It is appropriately sized for a simple tool and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter and an output schema, so the description need not explain return values. The description covers the essential action and non-destructive nature, making it sufficient for an agent to select and invoke the tool. However, slightly more detail on effects could push it higher.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the 'name' parameter (0% coverage), and the description does not compensate by explaining what 'name' refers to or any constraints (e.g., exact match, uniqueness). Since the parameter is not self-explanatory in the absence of context, the description falls short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Archive') and resource ('project'), and clarifies that it is 'kept, not deleted', which distinguishes it from a delete operation. This clearly states 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('archive' suggests removing from active use) but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention any alternative tools for achieving similar outcomes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear a task's 'needs attention' flag once the user has responded.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states the action (clearing a flag) and the trigger condition, but does not disclose idempotency, error behavior, or any side effects. This is adequate but leaves some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core action and the condition. Every word earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema provided), the description covers the essential what and when. It could mention idempotency or error cases, but the core context is complete for the intended use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implicitly maps 'task_id' to the task whose flag is cleared, providing basic semantic meaning. However, it does not explain how to obtain the task_id or any constraints, leaving room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('clear') and resource ('a task's 'needs attention' flag'), and the context 'once the user has responded' adds scoping. This clearly distinguishes it from sibling tool 'flag_attention' which likely sets the same flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('once the user has responded'), providing a clear usage context. It does not mention exclusions or alternatives, but the when-to-use condition is sufficient for this simple operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or update a label's description (creates the label if new).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| description | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It reveals that the tool creates the label if it does not exist, which is a meaningful side-effect. However, it does not mention permissions, overwrite semantics, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a parenthetical for edge-case behavior. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (two parameters, output schema present), the description covers the core functionality and the upsert condition. It does not address potential errors or permissions, but that is not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, so the description must explain the parameters. It implies that 'name' identifies the label and 'description' is the new text, and clarifies the create-if-new behavior. It does not provide detailed constraints or formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set or update') and the resource ('a label's description'), and the parenthetical adds a distinguishing upsert behavior. This differentiates it from task-centric siblings like add_task and list_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives such as list_labels or add_task. There is no explicit context or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task. Omit a field to leave it unchanged; pass an empty string
to clear an optional field (description, project, size, dates). Set
parent_id to re-parent (one level max), or clear_parent=true to detach.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| title | No | ||
| labels | No | ||
| project | No | ||
| task_id | Yes | ||
| due_date | No | ||
| priority | No | ||
| parent_id | No | ||
| description | No | ||
| clear_parent | No | ||
| scheduled_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the burden of behavioral disclosure. It explains that omitting a field leaves it unchanged and that an empty string clears optional fields, plus reparenting constraints. This is valuable beyond the schema, though it doesn't cover error cases 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, with the core action upfront and operational details following directly. Every phrase contributes meaning, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no annotations, the description covers the essential behavioral nuances needed to use it safely, including partial updates and clearing. With an output schema present, it doesn't need to describe return values. Minor gaps like validation rules or error handling prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description clarifies the global update semantics (omit vs null vs empty string) and specifically explains parent_id and clear_parent. It doesn't explicitly define every parameter like labels or priority, but the provided semantics resolve the most ambiguous aspects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action as 'Update a task' with a specific verb and resource, and notes non-obvious semantics around omitting vs clearing fields. It distinguishes itself from sibling tools like transition_task by focusing on general attribute edits, though it doesn't name explicit alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: use this tool when you need to modify existing task fields. However, it does not explicitly state when not to use it or mention alternative tools like transition_task for status changes, so guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag a task as awaiting the user's attention — e.g. you need a decision
or input to proceed. note should say what you need (a short question).
This makes the task stand out and rings a bell in the user's interactive
board. Call clear_attention once the user has responded.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It explains the effect ('makes the task stand out and rings a bell'), what the note should contain, and the lifecycle (clearing via clear_attention). It does not mention permissions or failure modes, but for a simple flagging operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action. Every sentence contributes: purpose, note instruction, and the clear_attention follow-up. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with an output schema, the description fully covers what, when, and how to invoke, plus the complementary follow-up. It is sufficiently complete without needing to explain return values (handled by output schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description explains `note` well: 'should say what you need (a short question).' The `task_id` parameter is self-explanatory from the tool's purpose (flagging a task), though not explicitly described. This largely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Flag a task as awaiting the user's attention.' This clearly distinguishes it from sibling tools like clear_attention (which removes the flag) and transition_task (which changes status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use context: 'e.g. you need a decision or input to proceed.' It also names the complementary tool and follow-up action: 'Call clear_attention once the user has responded.' This offers clear guidance on usage and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full task detail including status history and extracted references.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It does not explicitly state that this is a read-only operation, nor does it mention error behavior, permissions, or other side effects. The phrase 'Full task detail' implies retrieval but falls short of transparently describing the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core purpose ('Full task detail') and adds specific valuable details. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists and would fully document return values, so the description need not enumerate all fields. However, given the lack of annotations and usage guidance, the description is only minimally complete for a simple get-by-ID tool. It covers what is returned but not operational context like error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention task_id at all. Since the parameter is simple and self-explanatory, some may argue the schema alone is sufficient, but the description provides no added meaning, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (task) and the type of information (full detail, status history, extracted references), distinguishing it from list_tasks which likely returns summaries. However, it lacks an explicit verb like 'retrieves' or 'gets,' making it slightly less direct than ideal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when full task details are needed, but it offers no explicit guidance on when to use this tool over alternatives like list_tasks or search_tasks, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync external items into tasks, deduplicated by (source, external_id).
Each item needs 'external_id' (the stable dedup key within `source`) and
'title'; optional: description, url, project, labels, priority (1–5), size,
scheduled_date, due_date (ISO). Re-running upserts instead of duplicating:
new items are created, existing non-terminal ones have their title/description
refreshed (your triage is kept), terminal ones are left alone. With
`close_missing`, previously-ingested tasks absent from this batch are completed.| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| labels | No | ||
| source | Yes | ||
| project | No | ||
| close_missing | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly. It explains deduplication logic, upsert behavior (new items created, non-terminal refreshed, terminal left alone), the preservation of triage, and the close_missing flag's effect. This goes far beyond simple 'syncs tasks.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by concise requirements and behavioral details. Every sentence adds value, and the structure flows logically from purpose to fields to behavior. Despite its length, it remains tight and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex sync/upsert tool with an output schema present, the description covers the key semantics: dedup key, required vs optional fields, upsert behavior on re-run, handling of terminal states, and close_missing. It is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the crucial item fields (external_id, title, optional fields), the role of source in dedup, and close_missing behavior. However, the top-level 'labels' and 'project' parameters are mentioned only implicitly within the optional item fields, leaving some room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Sync external items into tasks,' and immediately clarifies the deduplication key (source, external_id). This clearly distinguishes it from sibling tools like add_task, which is for individual task creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its focus on syncing/upserting batches, but it does not explicitly state when to prefer this over add_task or other alternatives. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link the AI agent session you're working in to a task, so it can be
resumed later. agent is 'claude-code' or 'github-copilot-cli';
directory is the absolute working directory of this session; session_id
is this session's own id (used with --resume) if you know it; launcher is
the command or shell alias used to start the agent (it selects the profile,
e.g. 'claude-work') — omit to use the agent's default command. Re-linking
replaces any previous link. Call this when you start or resume work on a task.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | ||
| task_id | Yes | ||
| launcher | No | ||
| directory | Yes | ||
| session_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'Re-linking replaces any previous link,' which informs the user about the overwriting nature. It also explains parameter semantics that affect behavior (e.g., launcher selects profile). It does not mention auth requirements or error handling, but for a simple link operation, the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: it opens with the core purpose, then enumerates parameters in a readable list style, and closes with usage guidance. No sentence is wasted, and the length is appropriate for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, parameters, re-link overwrite behavior, and usage context. It does not explain the output schema or potential errors, but an output schema exists, so return values are not needed in the description. The missing explicit task_id explanation and lack of cross-reference to unlink_session are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite zero schema description coverage, the description compensates by explaining four of five parameters: agent, directory, session_id, and launcher. It leaves task_id undefined, but its meaning is inferable from the purpose ('task to a task'). Given the coverage, this is a strong performance, though a brief note on task_id would make it complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Link') and the specific resource (AI agent session to a task), with the purpose of resumption. It distinguishes itself from the sibling tool 'unlink_session' by implying the inverse operation, and it includes a clear call to action ('Call this when you start or resume work on a task').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Call this when you start or resume work on a task'). However, it does not explicitly mention when not to use it or point to the alternative 'unlink_session' for removing a link, though the sibling name makes this obvious. This is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List labels WITH descriptions — read these to know what each label means and when to apply it before labelling or prioritising.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral transparency. It discloses that the tool returns labels with descriptions and frames it as a read operation to inform labeling, implying no side effects. It lacks details on ordering or scope, but for a zero-parameter list operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action ('List labels WITH descriptions') and then explains the user benefit. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema is provided, the description fully covers the tool's purpose and usage context. It explains what is returned (labels with descriptions) and why to use it, making it complete for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. The description adds purpose context but no parameter syntax is needed, matching the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource 'labels' with a clarifying detail ('with descriptions'). It also explains the purpose ('read these to know what each label means and when to apply it'), clearly distinguishing it from the sibling `describe_label`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'before labelling or prioritising'. While it does not name alternatives or exclusion cases, the sibling context (e.g., `describe_label`) makes the intended use obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects.
| Name | Required | Description | Default |
|---|---|---|---|
| include_archived | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the bare action. It does not clarify whether archived projects are included by default, what authentication is needed, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with no wasted words, but it is under-specified rather than concise. A two-word restatement of the name fails to convey necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the output schema exists, return values are covered, but the description still lacks context about default filtering behavior and operational nuances. It is incomplete for a tool with an optional parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (include_archived) with zero coverage from description. The tool description does not mention this parameter at all, leaving its purpose and effect entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List projects.' exactly restates the tool name 'list_projects', making it a tautology. It provides no additional scope or differentiation from sibling tools like list_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There are no mentions of exclusions, prerequisites, or contexts where a different tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks with structured filters. By default terminal tasks
(completed/cancelled) are hidden unless include_terminal is true. Use
parent_id for one task's sub-tasks, or top_level_only to hide sub-tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | due | |
| sizes | No | ||
| labels | No | ||
| overdue | No | ||
| project | No | ||
| statuses | No | ||
| parent_id | No | ||
| due_before | No | ||
| no_project | No | ||
| priorities | No | ||
| top_level_only | No | ||
| include_terminal | No | ||
| scheduled_before | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals default terminal-task filtering and gives some parameter semantics, but does not describe interactions between filters, pagination, return format, or edge cases, leaving notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding distinct value: stating the core function, clarifying default filtering, and providing parameter guidance. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a complex tool with 13 optional parameters and no annotation support, the description covers only a small subset of available filters and does not address how parameters combine or what the response contains. The output schema may help, but the description alone leaves the tool inadequately specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only explains 3 of the 13 parameters (include_terminal, parent_id, top_level_only). The other 10 filters (sort, labels, statuses, due_before, priorities, etc.) receive no semantic explanation, so the description fails to compensate for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('List tasks') and qualifies it with 'structured filters', making the core function clear. It implicitly distinguishes from siblings like search_tasks by emphasizing structured filtering, but does not explicitly name alternatives or contrast behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical context on default behavior (terminal tasks hidden) and when to use specific parameters like parent_id vs top_level_only. However, it does not explain when to choose list_tasks over search_tasks or get_task, lacking explicit exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose a non-persistent day-by-day schedule of open tasks, greedily
packed into a daily focus budget (default from config) and ordered by
started-then-priority-then-due. Counts working days — weekends are skipped
unless include_weekends. Narrow the candidates with projects/labels
(include) or exclude_labels (drop private work); each falls back to config.
The suggested day is not saved to the task.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| labels | No | ||
| projects | No | ||
| capacity_hours | No | ||
| exclude_labels | No | ||
| include_weekends | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It does an excellent job: states the output is non-persistent, notes the exact ordering ('started-then-priority-then-due'), explains weekend handling, greedy packing, filter fallbacks, and explicitly states 'The suggested day is not saved to the task.' This is rich behavioral disclosure beyond what any annotation would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three information-dense sentences with no wasted words. It front-loads the core purpose, then covers weekend handling and filtering, and ends with the non-persistence caveat. Every clause adds value, and the structure is logical and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 optional parameters, planning logic, non-persistent behavior), the description covers the essential aspects: purpose, ordering, packing, weekend handling, filtering, fallback to config, and non-save guarantee. An output schema exists, so lack of return-format detail is acceptable. The description sufficiently equips an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameter meanings. It explains `include_weekends` (weekends skipped unless set), `projects`/`labels` (narrow candidates), `exclude_labels` (drop private work), and capacity via 'daily focus budget (default from config).' It does not explicitly mention the `days` parameter, but 'day-by-day schedule' and 'Counts working days' imply it. The description adds meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Propose a non-persistent day-by-day schedule of open tasks.' It specifies the resource (open tasks), the action (propose schedule), and key traits (greedily packed, ordered, non-persistent). It also distinguishes from siblings by emphasizing 'not saved to the task,' which differentiates it from persistence-oriented tools like agenda or task editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear behavioral context (weekends skipped, filtering via projects/labels, fallback to config) that implies when to use the tool: for proposing a schedule of open tasks. However, it does not explicitly state when to use this tool versus alternatives, nor does it name any alternative. The 'non-persistent' hint is the closest to an exclusion, but it is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search URLs extracted from task descriptions (fuzzy on url + anchor).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| domain | No | ||
| task_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions 'fuzzy on url + anchor', which is useful, but does not explain return format, pagination, case sensitivity, or the relationship between the search corpus and task descriptions. Minimal behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It front-loads the core purpose and behavior, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no annotations, no parameter descriptions), this description is too thin. It fails to explain how parameters affect the search, what 'fuzzy' matching entails in practice, or what output consumers can expect (even with an output schema, the search semantics are unspecified). The tool is underspecified for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% — the description does not explain any of the four parameters (limit, query, domain, task_id). While some parameters are self-explanatory (e.g., limit), the function of query relative to url/anchor, and the roles of domain and task_id, are left unspecified. The description does not compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the specific resource ('URLs extracted from task descriptions'), and the matching behavior ('fuzzy on url + anchor'). It distinguishes itself from sibling search_tasks by focusing on references/URLs rather than tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying the resource (URLs from task descriptions), but it does not explicitly state when to prefer this over alternatives or when not to use it. The distinction from search_tasks is implicit rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search tasks over title and description; ranked, best first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses fuzzy matching and ranking order, which are useful behavioral traits. But it omits details like case sensitivity, result limits, or potential side effects (though search is inherently read-only). It adds some value but lacks rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the operation and adds ranking info. No filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema covering return values, plus a simple two-parameter schema, the description sufficiently covers the search behavior and ordering. It lacks explicit usage exclusion, but the core information is present. The missing limit explanation is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It implicitly explains 'query' as the text matched against title/description, but the 'limit' parameter is entirely unmentioned. This leaves half the parameters semantically unexplained, so score is low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fuzzy-search' and identifies the resource 'tasks' and scope 'title and description', clearly distinguishing it from sibling tools like list_tasks (listing) and search_references (searching references).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the search behavior and matches against title/description, which conveys when to use this tool for find-by-text scenarios. However, it doesn't explicitly mention alternatives or when not to use it, so it stops 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.
Change a task's status, recording the transition (comment optional). Statuses: waiting, in_progress, blocked, completed, cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | ||
| task_id | Yes | ||
| to_status | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the transition is recorded and that a comment is optional, and it enumerates valid statuses. However, it omits other behavioral aspects like prerequisites, error handling, reversibility, or response behavior, leaving notable transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the primary action, and every clause adds value. No filler or redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema present, the description covers the core purpose, allowed statuses, and comment optionality. It is sufficiently complete for typical usage, though it could mention edge-case behavior like rejection of invalid statuses. Overall, it is almost fully contextualized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the to_status allowed values and the comment's optionality, but does not explicitly clarify task_id (though it is self-evident). This partial coverage warrants a mid-range score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely states the action ('Change a task's status') and the resource ('task'), and further clarifies the transition recording and optional comment. It also lists the allowed statuses, making the tool's scope unambiguous and distinguishing it from the broader edit_task sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for status transitions but does not explicitly state when to use it instead of edit_task or other alternatives. No exclusionary guidance is provided, so the usage context is only inferred from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove the AI session link from a task.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a mutating action by saying 'Remove', but it does not mention reversibility, permissions, behavior when no link exists, or side effects on the task. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb, and contains no unnecessary words. It is perfectly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the core function but lacks contextual guidance about preconditions, alternatives, or edge cases. The output schema may document return values, so that gap is acceptable, but the description is minimal overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for task_id (0% coverage), so the description must compensate. It adds that the action is performed 'from a task', implying task_id identifies the target task, but it does not clarify ID format, how to obtain it, or invalid-ID behavior. Minimal compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Remove' with a clear resource 'AI session link' and target 'a task', making the tool's function immediately obvious. It also distinguishes from the sibling 'link_session', which is clearly the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to remove a session link from a task, but it does not explicitly mention alternatives or when-not-to-use conditions. The sibling list provides some context, but the description itself offers no direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add_projectadd_taskagendaarchive_projectclear_attentiondescribe_labeledit_taskflag_attentionget_taskingestlink_sessionlist_labelslist_projectslist_tasksplansearch_referencessearch_taskstransition_taskunlink_sessionEach tool targets a distinct resource and action: tasks, projects, labels, sessions, attention flags, and bulk ingestion. Overlap is minimal, and descriptions clearly distinguish search_tasks from search_references and agenda from plan.
Most tools follow a clear verb_noun pattern (add_task, list_tasks, edit_task, link_session). A few exceptions like 'ingest', 'agenda', and 'plan' deviate from this pattern but remain readable and predictable.
With 19 tools covering task CRUD, status transitions, projects, labels, sessions, and planning, the count is well-scoped for the server's purpose. It is neither overly sparse nor bloated.
The surface covers most lifecycle needs: create/read/update/transition tasks, manage projects and labels, link sessions, and flag attention. Minor gaps exist, such as no hard delete for tasks and no session listing, but these are workable.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ptucholski/tasq'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
