Skip to main content
Glama

tasks_add

Creates a dependency-aware task in the ready queue, with optional gates for external blockers. Use it to add work that stays blocked until prerequisites finish or gates clear.

Instructions

Add a task to the dependency-aware ready queue. depends_on lists task ids that must finish first (done or dropped unblocks); each must exist and must not create a cycle. The task is 'ready' once it has no open/in_progress blocker and no open gate. A task that waits on a person or an event outside Seamless carries a gate: gate_who and gate_what on the step itself, or a task of kind gate that the waiting steps depend on, so one gate holds many steps and clearing it frees them all.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "title": "<title>"
    },
    "name": "tasks_add"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNooptional details / acceptance criteria (aliases: content, text)
kindNostep (the default: work an agent claims and finishes) or gate (a person's action, or an event outside Seamless, that the tasks depending on it wait for: never ready and never claimed; gate_who and gate_what describe it, and clearing it closes it and unblocks its dependents)
planNooptional plan slug (plan:<slug> convention) that composes this task as a step of a plan. Plan steps are excluded from the default ready-queue and surfaced under the plan filter.
titleYesshort task title
projectNoproject slug; defaults to the bound/ambient session's project. An unknown slug CREATES that project -- naming a new one is normal and never an error. Pass project=global ONLY for knowledge that belongs in EVERY project's briefing; it is not a neutral default. With no session and no explicit project the call is rejected as ambiguous. A session bound to a confidential or sealed project can write ONLY into that project.
sessionNothe session to act as: the name session_start returned, the cc/<id> or cx/<id> on your briefing's 'Seam session' line, or a session ULID. It scopes and credits this call. Defaults to this connection's session; pass it on every call when session_start reports the connection as stateless
gate_whoNowho must act before this task can go ahead: owner, founder:<name>, sitting:<name>, hardware, sealed:<project>, or free text (one line). With gate_what it gives the task a gate: a step whose gate is open is not ready, and tasks_ready lists it under gated
gate_whatNowhat must happen, one line (with gate_who)
depends_onNotask ids this task is blocked by (a comma-separated string is also accepted)
gate_decisionNooptional: the open question the person answers, one line
gate_ready_whenNooptional: when the task is ready, one line

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.10.1
    • addedInput schema / properties / gate_decision
      Added value: +{
      +  "description": "optional: the open question the person answers, one line",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_ready_when
      Added value: +{
      +  "description": "optional: when the task is ready, one line",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_what
      Added value: +{
      +  "description": "what must happen, one line (with gate_who)",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_who
      Added value: +{
      +  "description": "who must act before this task can go ahead: owner, founder:<name>, sitting:<name>, hardware, sealed:<project>, or free text (one line). With gate_what it gives the task a gate: a step whose gate is open is not ready, and tasks_ready lists it under gated",
      +  "type": "string"
      +}
    • addedInput schema / properties / kind
      Added value: +{
      +  "description": "step (the default: work an agent claims and finishes) or gate (a person's action, or an event outside Seamless, that the tasks depending on it wait for: never ready and never claimed; gate_who and gate_what describe it, and clearing it closes it and unblocks its dependents)",
      +  "enum": [
      +    "step",
      +    "gate"
      +  ],
      +  "type": "string"
      +}
  2. Changed1 schema field changedv0.7.4
    • addedInput schema / properties / session
      Added value: +{
      +  "description": "the session to act as: the name session_start returned, the cc/<id> or cx/<id> on your briefing's 'Seam session' line, or a session ULID. It scopes and credits this call. Defaults to this connection's session; pass it on every call when session_start reports the connection as stateless",
      +  "type": "string"
      +}
  3. Changed1 schema field changedv0.4.11
    • changedInput schema / properties / project / description
      Previous value: -"project slug; defaults to the bound/ambient session's project. An unknown slug CREATES that project -- naming a new one is normal and never an error. Pass project=global ONLY for knowledge that belongs in EVERY project's briefing; it is not a neutral default. With no session and no explicit project the call is rejected as ambiguous."New value: +"project slug; defaults to the bound/ambient session's project. An unknown slug CREATES that project -- naming a new one is normal and never an error. Pass project=global ONLY for knowledge that belongs in EVERY project's briefing; it is not a neutral default. With no session and no explicit project the call is rejected as ambiguous. A session bound to a confidential or sealed project can write ONLY into that project."
  4. First observedv0.1.0

TDQS

A4/5.0
Behavior5/5

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

Annotations only declare that this is a non-read-only, non-idempotent, non-destructive write. The description adds validation behavior ('each must exist and must not create a cycle'), the readiness rule (no open/in_progress blocker and no open gate), the unblock semantics of done/dropped, and the propagation rule that clearing one gate frees all dependents. That is substantial behavior beyond the structured hints and is consistent with idempotentHint=false.

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

Conciseness4/5

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

The action and its hardest constraint (dependency validity) are front-loaded in the first two sentences. The final sentence is long and partly re-explains the gate concept already present in the kind and gate_who schema descriptions, which is the only real padding.

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

Completeness4/5

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

For an 11-parameter write tool with no output schema, the definition covers dependencies, gates, readiness and project scoping well. The notable gap is that it never says what comes back on success — an agent needs the created task id to use later in depends_on, and this is only inferable from the sibling tools.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description contributes semantics the schema does not spell out: a blocker counts as cleared when it is 'done or dropped', and a single gate can hold many steps. Those clarifications help an agent decide what to pass in depends_on and gate_who.

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

Purpose4/5

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

The opening clause gives a specific verb and resource ('Add a task') and scopes it to the 'dependency-aware ready queue', which distinguishes it from queue readers like tasks_ready and mutators like tasks_update. It stops short of naming any sibling explicitly, so an agent must infer the boundary from the word 'add'.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the description explains how blocking and gating work once you have decided to add a task, but never says when to choose this over tasks_update (to change an existing task) or tasks_ready/tasks_list (to read the queue). There are no explicit exclusions or prerequisites for the call itself.

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