grr

Overview Schema Source Related Servers Discussions Admin

tasks.tasks.insert

Insert a new task into a specified task list by supplying its title, due date, notes, or other Task fields.

Instructions

Creates a new task on the specified task list. Tasks assigned from Docs or Chat Spaces cannot be inserted from Tasks Public API; they can only be created by assigning them from Docs or Chat Spaces. A user can have up to 20,000 non-hidden tasks per list and up to 100,000 tasks in total at a time [HTTP POST] — creates or triggers a change; refused under --readonly safety profiles. Returns the API's response resource as JSON — request body is a JSON Task object accepting assignmentInfo, completed, deleted, due, etag, hidden, id, kind and 9 more fields; pass it via params or whole via body_file Siblings over the same resource: clear, delete, get, list, move, patch, update.

Input Schema

Name	Required	Description
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`params`	No	Parameter map merged into the request; typed parameters win.
`parent`	No	[query parameter] Parent task identifier. If the task is created at the top level, this parameter is omitted. An assigned task cannot be a parent task, nor can it have a parent.
`dry_run`	No	Return the request that would be sent, without sending it.
`previous`	No	[query parameter] Previous sibling task identifier. If the task is created at the first position among its siblings, this parameter is omitted. Optional.
`tasklist`	Yes	[URL path segment] Task list identifier.
`body_file`	No	Read the request body from this file ('-' for stdin) instead of building one from the parameters. The body is a JSON Task object.
`request_body`	No	Request body of type Task: pass it via `params` (merged into the built body) or whole via `body_file`.

Output Schema

Name	Required	Description	Default
`id`	No
`due`	No
`etag`	No
`kind`	No
`links`	No
`notes`	No
`title`	No
`hidden`	No
`parent`	No
`status`	No
`deleted`	No
`updated`	No
`position`	No
`selfLink`	No
`completed`	No
`webViewLink`	No
`assignmentInfo`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 26, 2026

changedInput schema / properties / body_file / description

Previous value: -"Read the request body from this file ('-' for stdin) instead of building one from the parameters."New value: +"Read the request body from this file ('-' for stdin) instead of building one from the parameters. The body is a JSON Task object."

addedInput schema / properties / request_body

Added value: +{
+  "description": "Request body of type Task: pass it via `params` (merged into the built body) or whole via `body_file`.",
+  "properties": {
+    "assignmentInfo": {
+      "properties": {
+        "driveResourceInfo": {
+          "properties": {
+            "driveFileId": {
+              "type": "string"
+            },
+            "resourceKey": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "linkToTask": {
+          "type": "string"
+        },
+        "spaceInfo": {
+          "properties": {
+            "space": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "surfaceType": {
+          "enum": [
+            "CONTEXT_TYPE_UNSPECIFIED",
+            "GMAIL",
+            "DOCUMENT",
+            "SPACE"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "completed": {
+      "type": "string"
+    },
+    "deleted": {
+      "type": "boolean"
+    },
+    "due": {
+      "type": "string"
+    },
+    "etag": {
+      "type": "string"
+    },
+    "hidden": {
+      "type": "boolean"
+    },
+    "id": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "links": {
+      "items": {
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "link": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "notes": {
+      "type": "string"
+    },
+    "parent": {
+      "type": "string"
+    },
+    "position": {
+      "type": "string"
+    },
+    "selfLink": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "webViewLink": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed4 schema fields changedOct 26, 2026

changedInput schema / properties / parent / description

Previous value: -"Parent task identifier. If the task is created at the top level, this parameter is omitted. An assigned task cannot be a parent task, nor can it have a parent. "New value: +"[query parameter] Parent task identifier. If the task is created at the top level, this parameter is omitted. An assigned task cannot be a parent task, nor can it have a parent. "

changedInput schema / properties / previous / description

Previous value: -"Previous sibling task identifier. If the task is created at the first position among its siblings, this parameter is omitted. Optional."New value: +"[query parameter] Previous sibling task identifier. If the task is created at the first position among its siblings, this parameter is omitted. Optional."

changedInput schema / properties / tasklist / description

Previous value: -"Task list identifier."New value: +"[URL path segment] Task list identifier."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "assignmentInfo": {
+      "properties": {
+        "driveResourceInfo": {
+          "properties": {
+            "driveFileId": {
+              "type": "string"
+            },
+            "resourceKey": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "linkToTask": {
+          "type": "string"
+        },
+        "spaceInfo": {
+          "properties": {
+            "space": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "surfaceType": {
+          "enum": [
+            "CONTEXT_TYPE_UNSPECIFIED",
+            "GMAIL",
+            "DOCUMENT",
+            "SPACE"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "completed": {
+      "type": "string"
+    },
+    "deleted": {
+      "type": "boolean"
+    },
+    "due": {
+      "type": "string"
+    },
+    "etag": {
+      "type": "string"
+    },
+    "hidden": {
+      "type": "boolean"
+    },
+    "id": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "links": {
+      "items": {
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "link": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "notes": {
+      "type": "string"
+    },
+    "parent": {
+      "type": "string"
+    },
+    "position": {
+      "type": "string"
+    },
+    "selfLink": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string"
+    },
+    "webViewLink": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that this is a mutation ('creates or triggers a change'), that it is refused under --readonly safety profiles, quota limits (20,000 per list / 100,000 total), and that it returns the API's response resource as JSON. It still omits auth scope requirements and idempotency behavior, so it is not fully exhaustive.

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 description is front-loaded with the core purpose, followed by restrictions, HTTP/safety notes, body mechanics, and sibling context. It is dense but each clause adds relevant information; minor phrasing like 'and 9 more fields' is slightly awkward but not wasteful.

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 a mutation tool with no annotations, the description covers behavior, safety, quotas, return format, and body-passing mechanics. An output schema exists, so detailed return-value explanation is not needed. The only notable gap is auth/permission requirements, which keeps it from being fully complete.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 8 parameters and the nested Task body. The description adds some value by noting that the body can be passed via `params` or wholly via `body_file` and by listing several Task fields, but this largely restates what the schema already provides.

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?

States a specific verb ('Creates'), resource ('a new task'), and parent resource ('on the specified task list'). It also distinguishes the create operation from its siblings by naming them at the end.

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

Usage Guidelines4/5

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

Explicitly says assigned tasks from Docs or Chat Spaces cannot be inserted via this API, giving a clear when-not-to-use condition. It also lists sibling tools over the same resource, though it does not spell out which sibling to choose for each alternative use case.

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

Deploy Server