MCP tools

Every tool the Tasqr MCP server exposes, with its parameters, return shape and tier availability. The REST API mirrors each one.

Tasqr's MCP server exposes 29 tools. Every write tool that operates on tasks or tags takes a list (a single item is just a list of one), so there's no separate "batch" tool to learn. A plain user-role API key sees only the 19 non-admin tools in tools/list; admin and owner keys see all 29. The 10 admin-gated tools (create_tags, update_tags, delete_tags, update_member, put_org_dek, and the 5 team-write tools) are hidden from user-role listings for a cleaner tool palette, but are still enforced by role on every call. Hiding a tool is a UX nicety, not the authorization boundary.

create_tasks

Create 1 to 25 tasks in one call via the tasks list (a single task is just a list of one). Each item takes the fields below, plus an optional ref: a client-chosen label (unique within the call) that lets other items depend on it without knowing its UUID. Put ref:<name> entries in a dependent's blocked_by, mixed freely with real task UUIDs. Tasqr resolves refs to real task IDs, creates tasks in dependency order, and returns per-item results (in input order) mapping each ref to its created task_id. If your org has a tag vocabulary defined, tags are validated against it, and unknown tags are rejected.

The whole call is validated upfront: unknown refs, duplicate refs, dependency cycles between refs, unknown tags, invalid assignees, missing blocker UUIDs, or a quota breach (the call counts N tasks against your monthly quota) reject everything before anything is written. A call counts as one write against your per-minute rate limit regardless of how many tasks it contains, and N items against your monthly request allowance. Per item, title is capped at 256 characters, description at 4,096, and metadata at 4,096 bytes serialized.

JSON · tasks argument (single task){
  "tasks": [
    {"title": "Summarise Q2 earnings report", "description": "Full instructions..."}
  ]
}

JSON · tasks argument (batch with ref dependencies){
  "tasks": [
    {"ref": "design", "title": "Design schema", "description": "..."},
    {"ref": "impl",   "title": "Implement API", "description": "...",
     "blocked_by": ["ref:design"]},
    {"title": "Ship it", "description": "...",
     "blocked_by": ["ref:impl", "3f22c6cf-existing-uuid"]}
  ]
}

JSON · response{
  "created": 3,
  "results": [
    {"ref": "design", "task_id": "uuid-1", "status": "pending", "created_at": "...",
     "suggested_tags": [{"name": "docs", "score": 0.28}]},
    {"ref": "impl",   "task_id": "uuid-2", "status": "blocked", "created_at": "...",
     "suggested_tags": [{"name": "feature", "score": 0.24}, {"name": "bug", "score": 0.21}],
     "similar": [{"task_id": "uuid-9", "title": "Implement the API", "status": "in_progress"}]},
    {"ref": null,     "task_id": "uuid-3", "status": "blocked", "created_at": "..."}
  ]
}

A single-task call returns the same shape: read the created task off results[0].

suggested_tags is an advisory list of the org tags whose meaning best matches the new task's text, most-relevant first (each {name, score}, score 0–1). It is a hint only. Nothing is applied automatically; to accept a suggestion, issue an update_tasks adding those tag names. Tags already on the task are excluded. Only tags that have a description are candidates: a bare tag name isn't enough to match against. The key is absent (never empty-vs-null ambiguity) when there is no signal to give: the org has no described tags, the org uses client-side BYOK encryption (the server never sees your plaintext), or the suggestion couldn't be computed in time. Treat its absence as "no suggestion", not an error.

similar is an advisory list of {task_id, title, status} for existing open (non-terminal) tasks that look like near-duplicates of the one just created, a nudge to check before doing the same work twice. It is a hint only; nothing is merged or blocked automatically. Same absence semantics as suggested_tags: the key is simply absent when there's no near-duplicate, the org is BYOK, or the check couldn't complete in time, never an empty list vs. a signal distinction to parse. Available on every tier.

update_tasks

Update 1 to 25 tasks in one call via the updates list (a single update is just a list of one). Each item takes a required task_id plus any of the fields below. status is optional on each item: omit it to update fields without triggering a state transition or writing a state event. A note is required when closing a task (completed, failed, or cancelled). An assignee is required when transitioning out of a holding state (pending or blocked): provide one in the same item or use claim_next_task to auto-assign.

The whole call is validated upfront against the rules below, then applied sequentially in input order. If an item fails partway through, items already applied are not rolled back: the response includes "partial": true and per-item results showing which succeeded and which failed. A call counts as one write against your per-minute rate limit regardless of how many updates it contains, and N items against your monthly request allowance. Per item, description and note are capped at 4,096 characters, and metadata / output at 4,096 bytes serialized.

JSON · updates argument{
  "updates": [
    {"task_id": "uuid-1", "status": "completed", "note": "Done", "output": {"rows": 47}},
    {"task_id": "uuid-2", "priority": 1, "tags": ["urgent"]}
  ]
}

JSON · response (full success){
  "updated": 2,
  "results": [
    {"task_id": "uuid-1", "status": "completed", "updated_at": "..."},
    {"task_id": "uuid-2", "status": "in_progress", "updated_at": "..."}
  ]
}

JSON · response (partial failure at item 2){
  "updated": 1,
  "partial": true,
  "results": [
    {"task_id": "uuid-1", "status": "completed", "updated_at": "..."},
    {"task_id": "uuid-2", "error": "Invalid status transition"}
  ]
}

A single-update call returns the same shape: read the result off results[0].

get_tasks

Fetch 1 to 25 tasks by ID in one call via the task_ids list. Returns {"tasks": [...], "count": N, "not_found": [...]}: not_found lists any requested IDs that don't exist or aren't in your org (a missing ID is reported there, not raised as an error). Every task includes a dependencies array with live blocker status. A single-ID request also includes the full history array (state events in chronological order) on that task; a multi-ID request omits history to keep the response light.

JSON · task_ids argument (single task, includes history){
  "task_ids": ["uuid-1"]
}

JSON · response (single task){
  "tasks": [
    {"task_id": "uuid-1", "status": "completed", "dependencies": [],
     "history": [{"from_status": "pending", "to_status": "in_progress", "timestamp": "..."}, "..."],
     "...": "..."}
  ],
  "count": 1,
  "not_found": []
}

JSON · task_ids argument (multiple tasks){
  "task_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

JSON · response (multiple tasks, no history){
  "tasks": [
    {"task_id": "uuid-1", "status": "completed", "dependencies": [], "...": "..."},
    {"task_id": "uuid-2", "status": "blocked", "dependencies": [{"task_id": "uuid-1", "status": "completed"}], "...": "..."}
  ],
  "count": 2,
  "not_found": ["uuid-3"]
}

list_tasks

List tasks for your org with optional filters. Returns tasks, count, and an optional cursor: pass it back to fetch the next page.

Each item contains task_id, title, status, priority and updated_at, plus assignee, tags, blocked_by and parent_task_id when those are set. Fields that are null or empty are omitted from the response, so a missing key means the field is unset. description, metadata and output are not included: retrieve them with get_tasks, or set full: true to return complete tasks here.

search_tasks

Semantic recall over your org's task history (managed orgs only, WP3): finds tasks by meaning, not keyword match, and surfaces completed tasks' output so you can reuse prior work. Results always come back filled to limit, so judge relevance by score rather than by whether results exist. Free tier is windowed to the last 90 days; paid tiers (dev/pro/enterprise) search the whole history. Returns {"available": false, "reason": "byok"} for BYOK orgs (the server holds no vectors it can read) or "not_configured" if the org has no embedding model configured.

JSON · example response{
  "results": [
    {"task_id": "uuid", "title": "Fix login redirect bug", "status": "completed",
     "output": {"root_cause": "stale session cookie"}, "score": 0.83}
  ]
}

claim_next_task

Atomically claim the highest-priority pending task for your API key. Returns {"claimed": false} if no matching tasks exist, or {"claimed": true, "task": {...}} with the claimed task (now in_progress) and a lease_expires_at timestamp. Every update_tasks call renews the lease automatically. If the task sees no writes for the full lease duration, it is reclaimed and re-queued.

On success, the response also includes context: parent chain (up to 3) and this task's blockers with their output. Read it before starting work: it replaces the get_tasks calls you'd otherwise make. context may also include prior_art: a list of the most similar completed tasks ({task_id, title, output, score}) so you can reuse prior work instead of redoing it. context may also include runbook: the single best-matching distilled runbook for this kind of work ({topic, body, score}). See list_runbooks. Best-effort and advisory (paid tiers, managed orgs only): its absence carries no signal.

get_quota

Returns your current monthly usage: tier, limit, used, remaining, resets_at, and a requests object (limit, used, remaining) for the org's monthly request allowance. remaining is null for Enterprise (unlimited tasks); the request allowance is finite on every tier.

get_insights

Org flow health, recomputed every ~6 hours: stuck or churning tasks (as task_ids), throughput, cycle times, failure rates by tag, per-agent stats. A signal's task_ids lists at most its top 20 tasks; count is the full total. Paid tiers. Returns {"available": false, "reason": "not_computed_yet"} until the first computation runs. No parameters.

On pro/enterprise managed orgs, the response may also carry failure_clusters, an array of {label, count, share_pct} objects: weekly root-cause clusters of recent failures (e.g. {"label": "upstream rate limits", "count": 7, "share_pct": 23}), recomputed on a weekly cycle independent of the 6-hour insights refresh. The key is absent until the first weekly computation runs, and never appears for free/dev tiers or client-encrypted (BYOK) orgs.

list_runbooks

List your org's distilled runbooks: reusable "how this org does X" guides the platform learns from clusters of your completed tasks, recomputed weekly. Each entry is {runbook_id, topic, body, computed_at, member_count}. Requires pro or enterprise; free/dev tiers get an error. Returns {"available": false, "reason": "byok"} for client-encrypted (BYOK) orgs, since runbooks are managed-orgs-only in v1. The same best-matching runbook is also attached automatically to claim_next_task's context.runbook when relevant. See claim_next_task. No parameters.

get_standup

The fleet's report: a short natural-language summary of what your fleet did this period (what shipped, what failed, what's stuck or churning, and a few notable results). Pull it at session start for context. Requires a paid plan (dev/pro/enterprise); no free-tier taste. Three cadences are generated on a schedule: daily (tactical), weekly (review), monthly (strategic). Reports can be scoped to the whole org or to a single team: a team:<name> scope is visible to members of that team and to org admins/owners; any other caller gets a ToolError. Returns {"available": false, "reason": "not_computed_yet"} before the first scheduled run computes one, or {"available": false, "reason": "byok"} for client-encrypted (BYOK) orgs, which reports don't support yet. On success, returns scope, period, cadence, computed_at, a headline object (counts: completed, failed, open, stuck_count, top_failure_tag; a delta versus the previous report of the same scope+cadence once one exists), the report body (the prose), and history, headline stats for up to your last 10 reports for the same scope.

plan_tasks

Draft a dependency-wired task graph for a goal, in the same ref:/blocked_by format create_tasks accepts. Review it, then resubmit with create: true to actually create the tasks (or hand the draft to create_tasks yourself). Grounded in this org's own history: similar completed tasks, typical cycle time, common failure tags, and the best-matching distilled runbook, if any, not just what the model already knows. Each drafted task carries advisory suggested_tags drawn from your org's tag vocabulary (empty when none fits) and a priority; with create: true the tasks are created with their priority but no tags, so tags stay a deliberate choice. Requires pro or enterprise; free/dev tiers get an error. Returns {"available": false, "reason": "byok"} for client-encrypted (BYOK) orgs (planning is managed-orgs-only in v1), or {"available": false, "reason": "not_enabled"} if this environment has no planning/embedding model configured.

plan_tasks calls are metered against a monthly per-org allowance, separate from your task quota and request allowance (higher on enterprise than pro, see Pricing). The allowance is charged before the model is asked to generate a plan, so a call that fails after that point (an unusable model response) still counts against it: the same call simply raises an error rather than returning a draft, and is worth retrying or rephrasing the goal. Exhausting the allowance instead raises a ToolError ("Monthly plan_tasks allowance of <limit> reached for tier '<tier>'."). See POST /tasks/plan for the equivalent REST 429.

JSON · example response (create omitted){
  "plan": {
    "goal": "Migrate billing off the deprecated Stripe API",
    "tasks": [
      {"ref": "audit", "title": "Audit current Stripe API usage", "description": "...",
       "blocked_by": [], "suggested_tags": ["chore"], "priority": 2},
      {"ref": "migrate", "title": "Migrate webhook handlers", "description": "...",
       "blocked_by": ["ref:audit"], "suggested_tags": ["feature"], "priority": 2}
    ],
    "grounded_on": {
      "similar_tasks": 4,
      "cycle_time_days": 3.5,
      "top_failure_tag": "deploy",
      "runbook": "Rotating a Stripe API key"
    }
  },
  "plan_calls_remaining": 17,
  "created": null
}

grounded_on summarizes what the draft leaned on: similar_tasks is the count of comparable completed tasks recalled from your history; cycle_time_days and top_failure_tag are drawn from your org's flow-health insights (either may be null if not yet computed); runbook is the topic of the best-matching distilled runbook, or null if none matched.

With create: true, a successful submission replaces created: null with the list of created {task_id, ref} pairs. If the whole batch failed upfront validation, nothing is written and the response instead carries not_created: {"reason": "..."}. A rarer mid-batch failure (some items created, some not) adds partial: true and failed: [{ref, error}] alongside created, mirroring create_tasks's own partial-failure convention.

list_tags

List all tags defined for this organization. Returns an array of objects with name, strict, default, description, created_by, and created_at. Any member can call this. No role restriction.

Read the descriptions before you tag. They tell you what each tag is for, so you can pick a close existing tag rather than creating a new one: tier tag limits are tight, and a user-role agent cannot create tags at all. Pay closest attention to strict tags: a task tagged with the wrong strict tag can only be claimed by agents carrying that tag, so it strands in the queue rather than merely being mis-filed. description is null on tags created before descriptions existed.

create_tags

Add 1 to 25 tags in one call to the org vocabulary, via the tags list (a single tag is just a list of one). Requires admin or owner role. Tag names are lowercased and stripped. Returns {"created": N, "tags": [...]}. The whole call is validated upfront: duplicate names within the call, names that already exist, an overlong or missing-on-strict description, or exceeding the tier's tag limit (see Pricing) reject everything before anything is written.

JSON · tags argument{
  "tags": [
    {"name": "backend", "strict": true, "description": "Server-side work owned by the Backend team."},
    {"name": "urgent"}
  ]
}

JSON · response{
  "created": 2,
  "tags": [
    {"name": "backend", "strict": true, "default": false, "description": "Server-side work owned by the Backend team.", "created_by": "you@org.com", "created_at": "..."},
    {"name": "urgent", "strict": false, "default": false, "description": null, "created_by": "you@org.com", "created_at": "..."}
  ]
}

update_tags

Update 1 to 25 existing tags in one call, via the tags list (a single update is just a list of one). Requires admin or owner. Each item is patch-what's-given: only the fields you pass on that item are changed, an omitted field leaves it as-is, and description: null clears it. Returns {"updated": N, "tags": [...]}.

A strict tag must always carry a description, so turning strict on for a tag that has none requires setting both in the same item, and a strict tag's description cannot be cleared.

JSON · tags argument{
  "tags": [
    {"name": "backend", "description": null},
    {"name": "urgent", "default": true}
  ]
}

JSON · response{
  "updated": 2,
  "tags": [
    {"name": "backend", "strict": true, "default": false, "description": null, "created_by": "you@org.com", "created_at": "..."},
    {"name": "urgent", "strict": false, "default": true, "description": null, "created_by": "you@org.com", "created_at": "..."}
  ]
}

delete_tags

Remove 1 to 25 tags in one call from the org vocabulary, via the names list (a single delete is just a list of one). Requires admin or owner. Does not modify existing task tags: tasks already carrying a deleted tag are unaffected. The whole call is validated upfront. If any name is unknown, nothing is deleted.

JSON · names argument{
  "names": ["deprecated", "old-feature"]
}

JSON · response{
  "deleted": ["deprecated", "old-feature"],
  "count": 2
}

list_members

List all org members. Returns email, role, profile_tags, team_tags, seated, and joined_at for each member. Any member can call this.

update_member

Change a member's role, profile tags, and/or seat. Requires admin or owner. Promotion to owner requires the caller to be owner. Members may lower their own role (e.g. owner → admin) but never raise it. The last owner in an org cannot be demoted.

get_profile

Returns your own email, role, and profile_tags. No parameters.

update_profile

Update your own profile tags. Profile tags are used as the default tag filter when you call claim_next_task without an explicit tags argument. Tags are validated against the org vocabulary. Non-admin users cannot self-assign strict tags: they are silently dropped (existing strict tags on your profile are preserved).

list_teams

List the org's teams. A team bundles tags; members of a team inherit its tags (union across all their teams) on top of their own profile_tags. See Roles & tags. Requires a paid plan (dev/pro/enterprise); free-tier orgs get an upgrade error. No parameters.

get_team

Get one team including its members. Each member entry shows sources: a subset of manual / idp recording how they got there, so a membership added by an admin and later confirmed by IdP group push shows both.

create_team

Create a team. Requires admin or owner role and a paid plan (dev/pro/enterprise). Fails if the name already exists or the org has reached its tier's team limit (see Pricing). If the org has SSO with a matching IdP group name, membership can sync automatically instead of being assigned manually.

update_team

Update a team. Requires admin or owner role and a paid plan. Only the fields you pass are changed: omitting a field leaves it as-is. Pass tags: [] to clear all tags, or null as the description (an empty string also works) to clear it. Changing idp_only requires owner and an active IdP enrollment on the org.

delete_team

Delete a team. Its members keep their own profile_tags but lose the team's inherited tags. Requires admin or owner role.

add_team_member

Manually assign an org member to a team. Requires admin or owner role. Rejected on idp_only teams, so change the IdP group membership instead.

remove_team_member

Remove a manually-assigned member from a team. Requires admin or owner role. Rejected on idp_only teams, and on a membership that only came from IdP sync, so change the IdP group membership instead.

submit_feedback

Submit product feedback to the TASQR team. Does not count against your monthly task quota. Use this for bugs, feature requests, or general observations about TASQR itself, not for issues within your own task queue. Every submission passes through a content filter before it reaches the TASQR team: an abusive submission is rejected as a tool error (no task is created) and counts as a strike against the member who sent it. Strikes are counted across every key that member holds in the workspace, including revoked ones, so rotating a key does not reset them: enough strikes revokes all of that member's keys and blocks them from creating a new one, in that workspace or in a brand-new one, until a Tasqr operator lifts it. An org that accumulates enough strikes across its members is suspended. If the filter itself is unavailable, that's also a tool error; nothing is written and no strike is recorded. Retry shortly.

get_org_dek

Returns the org's client-supplied wrapped DEK configuration, including the org_id the client binds into its ciphertext AAD. Raises a tool error if the org has not configured client-side BYOK (i.e. the org uses Tasqr-managed encryption). Any API key can call this. No role restriction.

Returns {"wrapped_dek": "<base64>", "kms_key_id": "<arn>"}.

put_org_dek

Store a customer-supplied wrapped Data Encryption Key (DEK) to enable client-side BYOK. Returns {"status": "created", "org_id": ...}. Requires owner role. Raises a tool error if a DEK is already configured. Contact support to rotate.