teamgrid_list_create · TeamGrid Developer

Input schema, permissions, API mapping and write behavior for teamgrid_list_create.

teamgrid_list_create is a write-capable TeamGrid MCP tool. It is advertised in: full, catalog-write.

Create a list. Changes the selected workspace under current API permissions. Reuse the same idempotencyKey and payload for the same intent.

Arguments at a glance

The table describes full. When a profile variant is shown below, use that variant’s exact schema.

Argument	Presence	Type	Meaning
`workspaceId`	Required	string	Workspace returned by teamgrid_workspace_get and selected for this exact action.
`idempotencyKey`	Required	string	Stable key for this exact intent. Retain and reuse the same key and payload after a timeout; a timeout does not prove failure.
`data`	Required	object	Public API representation of list.

Input schema

Stable release: this is the exact JSON Schema advertised by @teamgrid/mcp-server@1.2.2:

{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Workspace returned by teamgrid_workspace_get and selected for this exact action."
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[\\x21-\\x7e]+$",
      "description": "Stable key for this exact intent. Retain and reuse the same key and payload after a timeout; a timeout does not prove failure."
    },
    "data": {
      "additionalProperties": false,
      "properties": {
        "name": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string",
          "description": "Human-readable name of the resource."
        },
        "parentId": {
          "maxLength": 128,
          "type": [
            "string",
            "null"
          ],
          "description": "Identifier of the parent resource, or null for a root resource."
        },
        "type": {
          "enum": [
            "tasks",
            "projects"
          ],
          "type": "string",
          "description": "Canonical type discriminator for this resource."
        }
      },
      "required": [
        "name",
        "type"
      ],
      "type": "object",
      "description": "Public API representation of list."
    }
  },
  "required": [
    "workspaceId",
    "idempotencyKey",
    "data"
  ],
  "additionalProperties": false
}

The schema above is for full. Properties not in the selected profile schema are rejected.

Scope and API operation

Required scopes (all): lists:write, workspace:read.

createList — POST /lists

The credential must also satisfy normal workspace authorization and any service-account resource grants. Selecting an MCP tool profile never adds scopes to a credential.

Write preconditions

Concurrency: unconditional. No top-level revision precondition is declared; do not assume conflict protection. Reuse idempotencyKey only for the same creation intent and exact payload.

Output and limits

A compact mutation receipt includes target and revision when available; outcome metadata distinguishes accepted, complete, partial and uncertain results. This tool returns a single API response envelope and is not paginated. The serialized result may not exceed 256 KiB.

Download the exact MCP input and output contract, including profile variants, scopes and safety annotations. Its outputSchema describes the advertised MCP envelope and local $defs; it includes MCP projection metadata in addition to the underlying API schema.

The linked API operation describes the business resource and its field semantics. Write tools preserve their declared revision/idempotency contract and require current permissions. Accepted jobs provide status/resume information; uncertain writes must not be replayed blindly.

Security classification

workspace-mutation: This changes workspace state and may trigger business or external effects. Use its exact scope, revision and idempotency contract; profile selection grants no authority.

The exact safety annotations are {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}. The host and model can still retain tool arguments and results in prompts, logs, or transcripts; use a dedicated least-privilege credential.

Example prompt

Prepare a teamgrid_list_create operation for my chosen target. Resolve IDs, read current state and revisions, show the intended change, then report its confirmed or uncertain outcome without automatic retries.

The prompt is illustrative. Inspect the proposed tool arguments before approving access to personal, commercial, conversation, or security-configuration data.

Common failures

Condition	Observable behavior and recovery
The selected tool profile or allow/deny filter excludes `teamgrid_list_create`.	The tool is not advertised to the host. Select the narrowest profile that contains it and restart the host.
An argument violates this tool’s input schema: required field, type, enum, pattern, length, or range.	MCP input validation rejects the call before an API request is made.
The credential lacks `lists:write` and `workspace:read` or cannot access the requested resource.	The tool preserves a safe API error code such as `insufficient_scope`, with redacted detail and available status/request metadata.
The connection ends while awaiting the write result.	Inspect the outcome and status/resume information. An interrupted wait does not prove rollback; never blindly repeat the write.
An unknown input property is supplied.	The strict input schema rejects the call before an API request is made.

Authentication failures that prevent the MCP process from starting are covered separately in MCP troubleshooting.

Back to all MCP tools · MCP security model