Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Manage Contacts Batch

manage_contacts_batch

Destructive

Batch create, update, or delete Google Contacts in a single call to consolidate contact changes and avoid multiple separate operations.

Instructions

Batch create, update, or delete contacts. Consolidated tool replacing batch_create_contacts, batch_update_contacts, and batch_delete_contacts.

Input Schema

Name	Required	Description
`field`	No	For "update" action, the single People API field to update across all contacts in this batch. Required. Must be one of: names, phoneNumbers, emailAddresses, organizations, nicknames, urls, userDefined, relations, biographies, addresses, birthdays. Using a single field per batch call prevents unintentional data loss from a union updateMask overwriting unrelated fields.
`action`	Yes	The action to perform: "create", "update", or "delete".
`updates`	No	List of update dicts for "update" action. Each dict must contain contact_id and may contain the same fields as contacts.
`contacts`	No	List of contact dicts for "create" action. Each dict may contain: given_name, family_name, phones, emails, organizations, nicknames, urls, user_defined, relations, notes, address, birthday. Deprecated: phone, email, organization, job_title.
`contact_ids`	No	List of contact IDs for "delete" action.
`user_google_email`	Yes	The user's Google email address. Required.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.2.0Oct 24, 2026

changedInput schema / properties / contacts / description

Previous value: -"List of contact dicts for \"create\" action.\nEach dict may contain: given_name, family_name, phones, emails, organizations,\nnotes, address. Deprecated: phone, email, organization, job_title."New value: +"List of contact dicts for \"create\" action.\nEach dict may contain: given_name, family_name, phones, emails,\norganizations, nicknames, urls, user_defined, relations, notes, address,\nbirthday. Deprecated: phone, email, organization, job_title."

changedInput schema / properties / field / description

Previous value: -"For \"update\" action — the single People API field to update across\nall contacts in this batch. Required. Must be one of: names, phoneNumbers,\nemailAddresses, organizations, nicknames, urls, userDefined, relations,\nbiographies, addresses, birthdays. Using a single field per batch call prevents\nunintentional data loss from a union updateMask overwriting unrelated fields."New value: +"For \"update\" action, the single People API field to update across\nall contacts in this batch. Required. Must be one of: names, phoneNumbers,\nemailAddresses, organizations, nicknames, urls, userDefined, relations,\nbiographies, addresses, birthdays. Using a single field per batch call prevents\nunintentional data loss from a union updateMask overwriting unrelated fields."

Changed12 schema fields changedv1.28.0Sep 24, 2026

removedInput schema / properties / contact_ids / anyOf

Removed value: -[
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / contact_ids / items
```
Added value: +{
+  "type": "string"
+}
```
addedInput schema / properties / contact_ids / type
```
Added value: +"array"
```

removedInput schema / properties / contacts / anyOf

Removed value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "description": "Typed batch-create input for a contact.",
-      "properties": {
-        "address": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "birthday": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Birthday as 'YYYY-MM-DD', 'MM-DD' (no year), or 'clear'/'' to remove."
-        },
-        "email": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "emails": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for an email entry.",
-                "properties": {
-                  "address": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Email address value."
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Email type such as work, home, or other."
-                  },
-                  "value": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Backward-compatible alias for the email address value."
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "family_name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "given_name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "job_title": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "nicknames": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a nickname entry.",
-                "properties": {
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Nickname type such as default, alternate_name, maiden_name, initials, or other."
-                  },
-                  "value": {
-                    "description": "Nickname value. Used for bilingual contacts (e.g. Hebrew alternative form).",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "value"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "notes": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "organization": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "organizations": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for an organization entry.",
-                "properties": {
-                  "department": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Department name."
-                  },
-                  "jobDescription": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Optional organization job description."
-                  },
-                  "name": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Organization name."
-                  },
-                  "title": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Job title."
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Organization type such as work or school."
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "phone": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "phones": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a phone entry.",
-                "properties": {
-                  "number": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Phone number value."
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Phone type such as mobile, work, home, or internal."
-                  },
-                  "value": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Backward-compatible alias for the phone number value."
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "relations": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a relation entry (spouse, parent, child, etc.).",
-                "properties": {
-                  "person": {
-                    "description": "The related person's name (matched against contact names by Google Assistant).",
-                    "type": "string"
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Relation type: spouse, child, parent, father, mother, sister, brother, friend, manager, assistant, partner, sibling, domesticPartner, or custom."
-                  }
-                },
-                "required": [
-                  "person"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "urls": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a URL entry.",
-                "properties": {
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "URL type such as homepage, blog, profile, work, ftp, reservations, or other. Custom values allowed."
-                  },
-                  "value": {
-                    "description": "The URL value (e.g. https://example.com).",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "value"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "user_defined": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a userDefined custom field entry.",
-                "properties": {
-                  "key": {
-                    "description": "Custom field key (e.g. 'ID', 'Hebrew Birthday', 'Account Number').",
-                    "type": "string"
-                  },
-                  "value": {
-                    "default": "",
-                    "description": "Custom field value. May be omitted when using remove mode (only the key is needed).",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "key"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / contacts / items

Added value: +{
+  "additionalProperties": false,
+  "description": "Typed batch-create input for a contact.",
+  "properties": {
+    "address": {
+      "default": null,
+      "type": "string"
+    },
+    "birthday": {
+      "default": null,
+      "description": "Birthday as 'YYYY-MM-DD', 'MM-DD' (no year), or 'clear'/'' to remove.",
+      "type": "string"
+    },
+    "email": {
+      "default": null,
+      "type": "string"
+    },
+    "emails": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for an email entry.",
+        "properties": {
+          "address": {
+            "default": null,
+            "description": "Email address value.",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Email type such as work, home, or other.",
+            "type": "string"
+          },
+          "value": {
+            "default": null,
+            "description": "Backward-compatible alias for the email address value.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "family_name": {
+      "default": null,
+      "type": "string"
+    },
+    "given_name": {
+      "default": null,
+      "type": "string"
+    },
+    "job_title": {
+      "default": null,
+      "type": "string"
+    },
+    "nicknames": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a nickname entry.",
+        "properties": {
+          "type": {
+            "default": null,
+            "description": "Nickname type such as default, alternate_name, maiden_name, initials, or other.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Nickname value. Used for bilingual contacts (e.g. Hebrew alternative form).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "notes": {
+      "default": null,
+      "type": "string"
+    },
+    "organization": {
+      "default": null,
+      "type": "string"
+    },
+    "organizations": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for an organization entry.",
+        "properties": {
+          "department": {
+            "default": null,
+            "description": "Department name.",
+            "type": "string"
+          },
+          "jobDescription": {
+            "default": null,
+            "description": "Optional organization job description.",
+            "type": "string"
+          },
+          "name": {
+            "default": null,
+            "description": "Organization name.",
+            "type": "string"
+          },
+          "title": {
+            "default": null,
+            "description": "Job title.",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Organization type such as work or school.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "phone": {
+      "default": null,
+      "type": "string"
+    },
+    "phones": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a phone entry.",
+        "properties": {
+          "number": {
+            "default": null,
+            "description": "Phone number value.",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Phone type such as mobile, work, home, or internal.",
+            "type": "string"
+          },
+          "value": {
+            "default": null,
+            "description": "Backward-compatible alias for the phone number value.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "relations": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a relation entry (spouse, parent, child, etc.).",
+        "properties": {
+          "person": {
+            "description": "The related person's name (matched against contact names by Google Assistant).",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Relation type: spouse, child, parent, father, mother, sister, brother, friend, manager, assistant, partner, sibling, domesticPartner, or custom.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "person"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "urls": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a URL entry.",
+        "properties": {
+          "type": {
+            "default": null,
+            "description": "URL type such as homepage, blog, profile, work, ftp, reservations, or other. Custom values allowed.",
+            "type": "string"
+          },
+          "value": {
+            "description": "The URL value (e.g. https://example.com).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "user_defined": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a userDefined custom field entry.",
+        "properties": {
+          "key": {
+            "description": "Custom field key (e.g. 'ID', 'Hebrew Birthday', 'Account Number').",
+            "type": "string"
+          },
+          "value": {
+            "default": "",
+            "description": "Custom field value. May be omitted when using remove mode (only the key is needed).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / contacts / type
```
Added value: +"array"
```

removedInput schema / properties / field / anyOf

Removed value: -[
-  {
-    "enum": [
-      "names",
-      "phoneNumbers",
-      "emailAddresses",
-      "organizations",
-      "nicknames",
-      "urls",
-      "userDefined",
-      "relations",
-      "biographies",
-      "addresses",
-      "birthdays"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / field / enum

Added value: +[
+  "names",
+  "phoneNumbers",
+  "emailAddresses",
+  "organizations",
+  "nicknames",
+  "urls",
+  "userDefined",
+  "relations",
+  "biographies",
+  "addresses",
+  "birthdays"
+]

addedInput schema / properties / field / type
```
Added value: +"string"
```

removedInput schema / properties / updates / anyOf

Removed value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "description": "Typed batch-update input for a contact.",
-      "properties": {
-        "address": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "birthday": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Birthday as 'YYYY-MM-DD', 'MM-DD' (no year), or 'clear'/'' to remove."
-        },
-        "contact_id": {
-          "description": "Contact ID like \"c123\" or full resource name like \"people/c123\".",
-          "type": "string"
-        },
-        "email": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "emails": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for an email entry.",
-                "properties": {
-                  "address": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Email address value."
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Email type such as work, home, or other."
-                  },
-                  "value": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Backward-compatible alias for the email address value."
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "family_name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "given_name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "job_title": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "nicknames": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a nickname entry.",
-                "properties": {
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Nickname type such as default, alternate_name, maiden_name, initials, or other."
-                  },
-                  "value": {
-                    "description": "Nickname value. Used for bilingual contacts (e.g. Hebrew alternative form).",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "value"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "notes": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "organization": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "organizations": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for an organization entry.",
-                "properties": {
-                  "department": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Department name."
-                  },
-                  "jobDescription": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Optional organization job description."
-                  },
-                  "name": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Organization name."
-                  },
-                  "title": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Job title."
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Organization type such as work or school."
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "phone": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "phones": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a phone entry.",
-                "properties": {
-                  "number": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Phone number value."
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Phone type such as mobile, work, home, or internal."
-                  },
-                  "value": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Backward-compatible alias for the phone number value."
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "relations": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a relation entry (spouse, parent, child, etc.).",
-                "properties": {
-                  "person": {
-                    "description": "The related person's name (matched against contact names by Google Assistant).",
-                    "type": "string"
-                  },
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "Relation type: spouse, child, parent, father, mother, sister, brother, friend, manager, assistant, partner, sibling, domesticPartner, or custom."
-                  }
-                },
-                "required": [
-                  "person"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "urls": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a URL entry.",
-                "properties": {
-                  "type": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ],
-                    "default": null,
-                    "description": "URL type such as homepage, blog, profile, work, ftp, reservations, or other. Custom values allowed."
-                  },
-                  "value": {
-                    "description": "The URL value (e.g. https://example.com).",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "value"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "user_defined": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "description": "Typed input for a userDefined custom field entry.",
-                "properties": {
-                  "key": {
-                    "description": "Custom field key (e.g. 'ID', 'Hebrew Birthday', 'Account Number').",
-                    "type": "string"
-                  },
-                  "value": {
-                    "default": "",
-                    "description": "Custom field value. May be omitted when using remove mode (only the key is needed).",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "key"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        }
-      },
-      "required": [
-        "contact_id"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / updates / items

Added value: +{
+  "additionalProperties": false,
+  "description": "Typed batch-update input for a contact.",
+  "properties": {
+    "address": {
+      "default": null,
+      "type": "string"
+    },
+    "birthday": {
+      "default": null,
+      "description": "Birthday as 'YYYY-MM-DD', 'MM-DD' (no year), or 'clear'/'' to remove.",
+      "type": "string"
+    },
+    "contact_id": {
+      "description": "Contact ID like \"c123\" or full resource name like \"people/c123\".",
+      "type": "string"
+    },
+    "email": {
+      "default": null,
+      "type": "string"
+    },
+    "emails": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for an email entry.",
+        "properties": {
+          "address": {
+            "default": null,
+            "description": "Email address value.",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Email type such as work, home, or other.",
+            "type": "string"
+          },
+          "value": {
+            "default": null,
+            "description": "Backward-compatible alias for the email address value.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "family_name": {
+      "default": null,
+      "type": "string"
+    },
+    "given_name": {
+      "default": null,
+      "type": "string"
+    },
+    "job_title": {
+      "default": null,
+      "type": "string"
+    },
+    "nicknames": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a nickname entry.",
+        "properties": {
+          "type": {
+            "default": null,
+            "description": "Nickname type such as default, alternate_name, maiden_name, initials, or other.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Nickname value. Used for bilingual contacts (e.g. Hebrew alternative form).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "notes": {
+      "default": null,
+      "type": "string"
+    },
+    "organization": {
+      "default": null,
+      "type": "string"
+    },
+    "organizations": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for an organization entry.",
+        "properties": {
+          "department": {
+            "default": null,
+            "description": "Department name.",
+            "type": "string"
+          },
+          "jobDescription": {
+            "default": null,
+            "description": "Optional organization job description.",
+            "type": "string"
+          },
+          "name": {
+            "default": null,
+            "description": "Organization name.",
+            "type": "string"
+          },
+          "title": {
+            "default": null,
+            "description": "Job title.",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Organization type such as work or school.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "phone": {
+      "default": null,
+      "type": "string"
+    },
+    "phones": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a phone entry.",
+        "properties": {
+          "number": {
+            "default": null,
+            "description": "Phone number value.",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Phone type such as mobile, work, home, or internal.",
+            "type": "string"
+          },
+          "value": {
+            "default": null,
+            "description": "Backward-compatible alias for the phone number value.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "relations": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a relation entry (spouse, parent, child, etc.).",
+        "properties": {
+          "person": {
+            "description": "The related person's name (matched against contact names by Google Assistant).",
+            "type": "string"
+          },
+          "type": {
+            "default": null,
+            "description": "Relation type: spouse, child, parent, father, mother, sister, brother, friend, manager, assistant, partner, sibling, domesticPartner, or custom.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "person"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "urls": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a URL entry.",
+        "properties": {
+          "type": {
+            "default": null,
+            "description": "URL type such as homepage, blog, profile, work, ftp, reservations, or other. Custom values allowed.",
+            "type": "string"
+          },
+          "value": {
+            "description": "The URL value (e.g. https://example.com).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "user_defined": {
+      "default": null,
+      "items": {
+        "additionalProperties": false,
+        "description": "Typed input for a userDefined custom field entry.",
+        "properties": {
+          "key": {
+            "description": "Custom field key (e.g. 'ID', 'Hebrew Birthday', 'Account Number').",
+            "type": "string"
+          },
+          "value": {
+            "default": "",
+            "description": "Custom field value. May be omitted when using remove mode (only the key is needed).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "contact_id"
+  ],
+  "type": "object"
+}

addedInput schema / properties / updates / type
```
Added value: +"array"
```

Addedv1.0.1Jul 31, 2026

TDQS

B3.2/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered externally. The description adds nothing behavioral beyond that: no statement that delete is permanent, no disclosure of partial-failure/atomicity semantics for a batch, no rate-limit or quota context. The only added information is the deprecation note about predecessor tool names.

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?

Two short sentences, front-loaded with the verb/resource and followed by the consolidation note. No filler. It is efficiently written, though the brevity is partly under-specification rather than pure economy.

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

Completeness3/5

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

With 6 parameters, three mutually exclusive payload arrays, and a destructive write surface, an agent still needs the description to clarify action-to-payload mapping and delete irreversibility. An output schema exists so return values needn't be explained, and annotations cover the read/write profile, which keeps this from being lower. Adequate but with clear gaps for a destructive batch tool.

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%, including a detailed rationale on the required `field` parameter (single field per batch to avoid union updateMask data loss), so the schema carries the parameter burden. The description itself says nothing about which parameter belongs to which action, so it neither compensates nor detracts. Baseline 3 applies.

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?

Uses a specific verb set (create/update/delete) on a specific resource (contacts) with the 'batch' scope qualifier, which separates it from sibling single-record tools like manage_contact, get_contact, and search_contacts. The mention of the three tools it replaces reinforces the batch identity. It stops short of naming a live sibling as the alternative route, so it lands at 4 rather than 5.

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?

The three supported actions are enumerated, so the agent can infer that this is for doing one of those operations across many contacts. But there is no explicit when-to-use versus manage_contact (single contact) or list_contacts/search_contacts, and no note that exactly one of contacts/updates/contact_ids is required per action beyond what the schema implies.

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

Deploy Server