Skip to main content
Glama

Create task

create_task

Create a task after the user has specified the target project and intended task. The connected user is assigned by default; assigneeIds overrides this, and [] leaves the task unassigned. Only set dates, priority, list or assignees when requested. Use content for Markdown or description for the legacy body, never both. Initial status must belong to the project. Attaching existing files additionally requires files:write. figmaDesigns embeds the designs and links Resources. If resources are pending, report the created task and retry this exact requestId on the same connection to finish linking, never create a replacement.

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": {
      "requestId": "<requestId>",
      "projectId": "<projectId>",
      "name": "<name>"
    },
    "name": "create_task"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesThe name requested by the user. For updates, omit to keep the current name.
listIdNoOptional existing task list ID in the destination project.
contentNoInitial Doc body as Markdown, at most 20,000 characters.
fileIdsNoUp to 20 existing accessible file IDs to attach. Requires files:write as well as tasks:write.
deadlineNoISO 8601 deadline including a timezone offset. Omit to leave unchanged; null clears the deadline.
priorityNoPriority: 0 Low, 1 Normal, 2 High, 3 Urgent. For updates, null clears it.
projectIdYesExisting accessible project ID returned by list_projects.
requestIdYesA unique UUID for this intended action. Reuse it unchanged when retrying the same action.
startDateNoISO 8601 start date with timezone. Omit to preserve; null clears it.
assigneeIdsNoFull replacement list of existing project member IDs from list_project_members. [] unassigns everyone; omit to preserve.
descriptionNoOptional text for the new task or the initial project document.
figmaDesignsNoSelected Figma designs to embed automatically; tasks also add them to Resources. Use content for Markdown, not legacy description. Ask for the design link if unavailable. Does not write back into Figma.
stateProjectIdNoTask status ID from list_project_statuses for the destination project.

Output Schema

NameRequiredDescriptionDefault
taskYes
figmaNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • addedInput schema / properties / assigneeIds
      Added value: +{
      +  "description": "Full replacement list of existing project member IDs from list_project_members. [] unassigns everyone; omit to preserve.",
      +  "items": {
      +    "maxLength": 100,
      +    "minLength": 1,
      +    "pattern": "^[A-Za-z0-9_-]+$",
      +    "type": "string"
      +  },
      +  "maxItems": 50,
      +  "type": "array"
      +}
    • addedInput schema / properties / content
      Added value: +{
      +  "description": "Initial Doc body as Markdown, at most 20,000 characters.",
      +  "maxLength": 20000,
      +  "type": "string"
      +}
    • addedInput schema / properties / figmaDesigns
      Added value: +{
      +  "description": "Selected Figma designs to embed automatically; tasks also add them to Resources. Use content for Markdown, not legacy description. Ask for the design link if unavailable. Does not write back into Figma.",
      +  "items": {
      +    "properties": {
      +      "name": {
      +        "description": "Design name supplied by Figma or the user.",
      +        "maxLength": 500,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "url": {
      +        "description": "Actual Figma design/file URL for the selected frame, section or page, including node-id. Never invent it.",
      +        "format": "uri",
      +        "maxLength": 2048,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "url"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 20,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / listId
      Added value: +{
      +  "description": "Optional existing task list ID in the destination project.",
      +  "maxLength": 100,
      +  "minLength": 1,
      +  "pattern": "^[A-Za-z0-9_-]+$",
      +  "type": "string"
      +}
    • addedInput schema / properties / priority
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 3,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Priority: 0 Low, 1 Normal, 2 High, 3 Urgent. For updates, null clears it."
      +}
    • addedInput schema / properties / startDate
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "date-time",
      +      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "ISO 8601 start date with timezone. Omit to preserve; null clears it."
      +}
    • addedOutput schema / properties / figma
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "backlinkCreated": {
      +      "const": false,
      +      "type": "boolean"
      +    },
      +    "designs": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "name": {
      +            "description": "Design name supplied by Figma or the user.",
      +            "maxLength": 500,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "url": {
      +            "description": "Actual Figma design/file URL for the selected frame, section or page, including node-id. Never invent it.",
      +            "format": "uri",
      +            "maxLength": 2048,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "url"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "docPageListingUpdated": {
      +      "const": false,
      +      "type": "boolean"
      +    },
      +    "pendingResources": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "name": {
      +            "description": "Design name supplied by Figma or the user.",
      +            "maxLength": 500,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "url": {
      +            "description": "Actual Figma design/file URL for the selected frame, section or page, including node-id. Never invent it.",
      +            "format": "uri",
      +            "maxLength": 2048,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "url"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "resources": {
      +      "enum": [
      +        "linked",
      +        "pending",
      +        "not_applicable"
      +      ],
      +      "type": "string"
      +    },
      +    "warning": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "designs",
      +    "resources",
      +    "pendingResources",
      +    "backlinkCreated"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / stateProjectId / description
      Previous value: -"Initial task status ID from list_project_statuses for the destination project."New value: +"Task status ID from list_project_statuses for the destination project."
  3. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description goes well beyond them: default assignee behavior, [] semantics for assigneeIds, the extra files:write permission requirement, and a non-obvious partial-failure mode where resources stay pending and the call must be retried with the same requestId rather than repeated as a new creation. The retry language sits in mild tension with idempotentHint=false, but it is framed as resuming the same requestId rather than as general idempotency, so it reads as clarification rather than contradiction.

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?

Purpose is front-loaded in sentence one and every subsequent sentence carries a distinct rule with no filler. The prose is dense and packs several rules per sentence, which costs a little readability but wastes no words.

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

Completeness5/5

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

For a 13-parameter mutation tool with an output schema (so return values need not be described), the definition covers permissions, defaulting, field exclusivity, cross-entity validation and the partial-failure retry path. Nothing an agent needs in order to call it correctly on the first attempt is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not carry: the connected user is assigned by default and assigneeIds overrides it, content and description are mutually exclusive, stateProjectId must be a status belonging to the destination project, and figmaDesigns also writes into Resources without writing back to Figma. These are selection rules, not restatements of field docs.

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

Purpose5/5

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

Opening sentence states a specific verb and resource ("Create a task") and adds the precondition that the user has specified the target project and intended task. "create_task" is trivially separable from siblings like update_task, create_doc and create_project on verb alone, and the description reinforces it with create-specific constraints (requestId, initial status, default assignee).

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

Usage Guidelines5/5

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

Explicit when-not guidance is given: "Only set dates, priority, list or assignees when requested" and "Use content for Markdown or description for the legacy body, never both." It also gives prerequisites (status must belong to the project, files:write needed for attachments) and a fallback path (report the created task and retry the same requestId) so the agent has a prescribed recovery action.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.