Skip to main content
Glama
epinethrone

icloud-mcp

by epinethrone
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

contacts_update_group

Idempotent

Rename an existing iCloud contact group and/or add or remove members without touching contact cards. Use it to change a group's name or membership; create or delete groups and contacts elsewhere.

Instructions

Rename one existing contact group and/or add or remove its members, without touching any contact card.

Use when: the owner asks to rename a group or change who is in it. Not for creating a group (use contacts_create_group), deleting one (use contacts_delete_group), or deleting a person (use contacts_delete_contact). Parameters:

  • uid from contacts_list_groups.

  • Omit name to keep it; a new name is 1-100 characters.

  • add_members are person uids from contacts_search_contacts, each checked to exist; uids already in the group are skipped.

  • remove_members uids not in the group are ignored.

  • Pass any combination of the three. Behavior:

  • Removing someone from a group never deletes their contact; other data on the group card is kept.

  • The write is conditional on the version last read, so a group changed elsewhere since is not overwritten.

  • Repeating the same call changes nothing.

  • A rename to a name another group already has (ignoring case and accents) is refused.

  • Not available when the server runs READ_ONLY. Returns: {updated: true, uid, name, members (new count)} plus added and removed (the uids that actually changed); {updated: false, note: "Nothing to change."} when nothing differs. Errors: "No group with uid"; "Not contacts in this address book: ..." for unknown add_members (nothing is written); "This contact changed since it was read": read the group again and retry.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
uidYesGroup uid from contacts_list_groups.
nameNoNew name; omit to keep.
add_membersNoContact uids (from contacts_search_contacts).
remove_membersNoContact uids (from contacts_search_contacts).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "title": "contacts_update_groupDictOutput",
-  "type": "object"
-}New value: +null
  2. Changed2 schema fields changedv0.12.0
    • changedInput schema / properties / add_members / description
      Previous value: -"Contact uids (from contacts_search)."New value: +"Contact uids (from contacts_search_contacts)."
    • changedInput schema / properties / remove_members / description
      Previous value: -"Contact uids (from contacts_search)."New value: +"Contact uids (from contacts_search_contacts)."
  3. Addedv0.11.0

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description goes well beyond them: version-conditional writes preventing clobbering, rename clashing refused ignoring case/accents, READ_ONLY server unavailability, removal never deleting the contact, and idempotent no-op semantics. These are the exact traits an agent needs before mutating a group.

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

Conciseness5/5

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

Front-loads the one-line purpose, then organizes the rest into Use when / Parameters / Behavior / Returns / Errors sections. Though long, every line carries distinct operational information with no padding.

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?

With no output schema, the description carries the return-shape burden and does so fully ({updated, uid, name, members count} plus added/removed, the no-change response, and the three exact error strings with remediation for the version conflict). Complete for a conditional mutation tool.

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

Parameters5/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 adds real meaning the schema lacks: uid must come from contacts_list_groups, name is optional and 1-100 characters, add_members are existence-checked and deduplicated, remove_members not present are silently ignored, and all three can be combined.

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?

Opens with a specific verb set and resource ('Rename one existing contact group and/or add or remove its members') and immediately scopes it against adjacent operations ('without touching any contact card'). This cleanly distinguishes it from contacts_create_group, contacts_delete_group, and contacts_update_contact.

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?

An explicit 'Use when' line states the trigger condition, and it names the three sibling tools to use instead for creating, deleting a group, or deleting a person. Nothing is left to inference.

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

Deploy Server

Other Tools