grr

Overview Schema Source Related Servers Discussions Admin

chat.spaces.messages.list

Lists messages from a Google Chat space you belong to, with filtering, ordering, pagination, and optional deleted messages; system messages are excluded.

Instructions

Lists messages in a space that the caller is a member of, including messages from blocked members and spaces. System messages, like those announcing new space members, aren't included. If you list messages from a space with no messages, the response is an empty object. When using a REST/HTTP interface, the response contains an empty JSON object, {}. For an example, see List messages. Supports the following types of authentication: - [App authentic [HTTP GET]. Returns the requested resource as JSON — request bodies are built from the typed parameters (typed flags win over the params map), or read whole from body_file Siblings over the same resource: create, delete, get, patch, replaceCards, search, update.

Input Schema

Name	Required	Description
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`filter`	No	[query parameter] Optional. A query filter. You can filter messages by date (`create_time`) and thread (`thread.name`). To filter messages by the date they were created, specify
`params`	No	Parameter map merged into the request; typed parameters win.
`parent`	Yes	[URL path segment] Required. The resource name of the space to list messages from. Format: `spaces/{space}`
`dry_run`	No	Return the request that would be sent, without sending it.
`orderBy`	No	[query parameter] Optional. How the list of messages is ordered. Specify a value to order by an ordering operation. Valid ordering operation values are as follows: - `ASC` for as
`pageSize`	No	[query parameter] Optional. The maximum number of messages returned. The service might return fewer messages than this value. If unspecified, at most 25 are returned. The maximum
`body_file`	No	Read the request body from this file ('-' for stdin) instead of building one from the parameters.
`pageToken`	No	[query parameter] Optional. A page token received from a previous list messages call. Provide this parameter to retrieve the subsequent page. When paginating, all other parameter
`showDeleted`	No	[query parameter] Optional. Whether to include deleted messages. Deleted messages include deleted time and metadata about their deletion, but message content is unavailable.
`markupSyntax`	No	[query parameter] Optional. Specifies the desired output syntax for the Chat message `formatted_text` field. Values: `MARKUP_SYNTAX_UNSPECIFIED` = Represents the unspecified value.; `MARKUP_SYNTAX_CHAT` = Uses Google Chat's markup syntax. See https://developers.google.com/workspace/chat/format-messages#format-texts for more information.; `MARKUP_SYNTAX_MARKDOWN` = Uses Markdown syntax. This syntax is based on the [CommonMark](https://commonmark.org/help/) specification, with additional extensions. See https://developers.google.com/workspace/chat/format-messages#format-texts for more information..

Output Schema

Name	Required	Description	Default
`messages`	No
`nextPageToken`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 26, 2026

changedInput schema / properties / filter / description

Previous value: -"Optional. A query filter. You can filter messages by date (`create_time`) and thread (`thread.name`). To filter messages by the date they were created, specify "New value: +"[query parameter] Optional. A query filter. You can filter messages by date (`create_time`) and thread (`thread.name`). To filter messages by the date they were created, specify "

changedInput schema / properties / markupSyntax / description

Previous value: -"Optional. Specifies the desired output syntax for the Chat message `formatted_text` field."New value: +"[query parameter] Optional. Specifies the desired output syntax for the Chat message `formatted_text` field. Values: `MARKUP_SYNTAX_UNSPECIFIED` = Represents the unspecified value.; `MARKUP_SYNTAX_CHAT` = Uses Google Chat's markup syntax. See https://developers.google.com/workspace/chat/format-messages#format-texts for more information.; `MARKUP_SYNTAX_MARKDOWN` = Uses Markdown syntax. This syntax is based on the [CommonMark](https://commonmark.org/help/) specification, with additional extensions. See https://developers.google.com/workspace/chat/format-messages#format-texts for more information.."

changedInput schema / properties / orderBy / description

Previous value: -"Optional. How the list of messages is ordered. Specify a value to order by an ordering operation. Valid ordering operation values are as follows: - `ASC` for as"New value: +"[query parameter] Optional. How the list of messages is ordered. Specify a value to order by an ordering operation. Valid ordering operation values are as follows: - `ASC` for as"

changedInput schema / properties / pageSize / description

Previous value: -"Optional. The maximum number of messages returned. The service might return fewer messages than this value. If unspecified, at most 25 are returned. The maximum"New value: +"[query parameter] Optional. The maximum number of messages returned. The service might return fewer messages than this value. If unspecified, at most 25 are returned. The maximum"

addedInput schema / properties / pageSize / format
```
Added value: +"int32"
```

changedInput schema / properties / pageToken / description

Previous value: -"Optional. A page token received from a previous list messages call. Provide this parameter to retrieve the subsequent page. When paginating, all other parameter"New value: +"[query parameter] Optional. A page token received from a previous list messages call. Provide this parameter to retrieve the subsequent page. When paginating, all other parameter"

changedInput schema / properties / parent / description

Previous value: -"Required. The resource name of the space to list messages from. Format: `spaces/{space}`"New value: +"[URL path segment] Required. The resource name of the space to list messages from. Format: `spaces/{space}`"

addedInput schema / properties / parent / pattern
```
Added value: +"^spaces/[^/]+$"
```

changedInput schema / properties / showDeleted / description

Previous value: -"Optional. Whether to include deleted messages. Deleted messages include deleted time and metadata about their deletion, but message content is unavailable."New value: +"[query parameter] Optional. Whether to include deleted messages. Deleted messages include deleted time and metadata about their deletion, but message content is unavailable."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "messages": {
+      "items": {
+        "properties": {
+          "accessoryWidgets": {
+            "items": {
+              "properties": {
+                "buttonList": {
+                  "properties": {
+                    "buttons": {
+                      "items": {
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "actionResponse": {
+            "properties": {
+              "dialogAction": {
+                "properties": {
+                  "actionStatus": {
+                    "type": "object"
+                  },
+                  "dialog": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "type": {
+                "enum": [
+                  "TYPE_UNSPECIFIED",
+                  "NEW_MESSAGE",
+                  "UPDATE_MESSAGE",
+                  "UPDATE_USER_MESSAGE_CARDS",
+                  "REQUEST_CONFIG",
+                  "DIALOG",
+                  "UPDATE_WIDGET"
+                ],
+                "type": "string"
+              },
+              "updatedWidget": {
+                "properties": {
+                  "suggestions": {
+                    "type": "object"
+                  },
+                  "widget": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "annotations": {
+            "items": {
+              "properties": {
+                "customEmojiMetadata": {
+                  "properties": {
+                    "customEmoji": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "length": {
+                  "type": "integer"
+                },
+                "richLinkMetadata": {
+                  "properties": {
+                    "calendarEventLinkData": {
+                      "type": "object"
+                    },
+                    "chatSpaceLinkData": {
+                      "type": "object"
+                    },
+                    "driveLinkData": {
+                      "type": "object"
+                    },
+                    "meetSpaceLinkData": {
+                      "type": "object"
+                    },
+                    "richLinkType": {
+                      "enum": [
+                        "RICH_LINK_TYPE_UNSPECIFIED",
+                        "DRIVE_FILE",
+                        "CHAT_SPACE",
+                        "GMAIL_MESSAGE",
+                        "MEET_SPACE",
+                        "CALENDAR_EVENT"
+                      ],
+                      "type": "string"
+                    },
+                    "uri": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "slashCommand": {
+                  "properties": {
+                    "bot": {
+                      "type": "object"
+                    },
+                    "commandId": {
+                      "type": "string"
+                    },
+                    "commandName": {
+                      "type": "string"
+                    },
+                    "triggersDialog": {
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "enum": [
+                        "TYPE_UNSPECIFIED",
+                        "ADD",
+                        "INVOKE"
+                      ],
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "startIndex": {
+                  "type": "integer"
+                },
+                "type": {
+                  "enum": [
+                    "ANNOTATION_TYPE_UNSPECIFIED",
+                    "USER_MENTION",
+                    "SLASH_COMMAND",
+                    "RICH_LINK",
+                    "CUSTOM_EMOJI"
+                  ],
+                  "type": "string"
+                },
+                "userMention": {
+                  "properties": {
+                    "type": {
+                      "enum": [
+                        "TYPE_UNSPECIFIED",
+                        "ADD",
+                        "MENTION"
+                      ],
+                      "type": "string"
+                    },
+                    "user": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "argumentText": {
+            "type": "string"
+          },
+          "attachedGifs": {
+            "items": {
+              "properties": {
+                "uri": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "attachment": {
+            "items": {
+              "properties": {
+                "attachmentDataRef": {
+                  "properties": {
+                    "attachmentUploadToken": {
+                      "type": "string"
+                    },
+                    "resourceName": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "contentName": {
+                  "type": "string"
+                },
+                "contentType": {
+                  "type": "string"
+                },
+                "downloadUri": {
+                  "type": "string"
+                },
+                "driveDataRef": {
+                  "properties": {
+                    "driveFileId": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "source": {
+                  "enum": [
+                    "SOURCE_UNSPECIFIED",
+                    "DRIVE_FILE",
+                    "UPLOADED_CONTENT"
+                  ],
+                  "type": "string"
+                },
+                "thumbnailUri": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "cards": {
+            "items": {
+              "properties": {
+                "cardActions": {
+                  "items": {
+                    "properties": {
+                      "actionLabel": {
+                        "type": "string"
+                      },
+                      "onClick": {
+                        "type": "object"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "header": {
+                  "properties": {
+                    "imageStyle": {
+                      "enum": [
+                        "IMAGE_STYLE_UNSPECIFIED",
+                        "IMAGE",
+                        "AVATAR"
+                      ],
+                      "type": "string"
+                    },
+                    "imageUrl": {
+                      "type": "string"
+                    },
+                    "subtitle": {
+                      "type": "string"
+                    },
+                    "title": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "sections": {
+                  "items": {
+                    "properties": {
+                      "header": {
+                        "type": "string"
+                      },
+                      "widgets": {
+                        "items": {
+                          "type": "object"
+                        },
+                        "type": "array"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "cardsV2": {
+            "items": {
+              "properties": {
+                "card": {
+                  "properties": {
+                    "cardActions": {
+                      "items": {
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "displayStyle": {
+                      "enum": [
+                        "DISPLAY_STYLE_UNSPECIFIED",
+                        "PEEK",
+                        "REPLACE"
+                      ],
+                      "type": "string"
+                    },
+                    "expressionData": {
+                      "items": {
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "fixedFooter": {
+                      "type": "object"
+                    },
+                    "header": {
+                      "type": "object"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "peekCardHeader": {
+                      "type": "object"
+                    },
+                    "sectionDividerStyle": {
+                      "enum": [
+                        "DIVIDER_STYLE_UNSPECIFIED",
+                        "SOLID_DIVIDER",
+                        "NO_DIVIDER"
+                      ],
+                      "type": "string"
+                    },
+                    "sections": {
+                      "items": {
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "type": "object"
+                },
+                "cardId": {
+                  "type": "string"
+                },
+                "ownerUser": {
+                  "properties": {
+                    "avatarUrl": {
+                      "type": "string"
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "domainId": {
+                      "type": "string"
+                    },
+                    "email": {
+                      "type": "string"
+                    },
+                    "isAnonymous": {
+                      "type": "boolean"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "type": {
+                      "enum": [
+                        "TYPE_UNSPECIFIED",
+                        "HUMAN",
+                        "BOT"
+                      ],
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "clientAssignedMessageId": {
+            "type": "string"
+          },
+          "createTime": {
+            "type": "string"
+          },
+          "deleteTime": {
+            "type": "string"
+          },
+          "deletionMetadata": {
+            "properties": {
+              "deletionType": {
+                "enum": [
+                  "DELETION_TYPE_UNSPECIFIED",
+                  "CREATOR",
+                  "SPACE_OWNER",
+                  "ADMIN",
+                  "APP_MESSAGE_EXPIRY",
+                  "CREATOR_VIA_APP",
+                  "SPACE_OWNER_VIA_APP",
+                  "SPACE_MEMBER"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "emojiReactionSummaries": {
+            "items": {
+              "properties": {
+                "emoji": {
+                  "properties": {
+                    "customEmoji": {
+                      "type": "object"
+                    },
+                    "unicode": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "reactionCount": {
+                  "type": "integer"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "fallbackText": {
+            "type": "string"
+          },
+          "formattedText": {
+            "type": "string"
+          },
+          "lastUpdateTime": {
+            "type": "string"
+          },
+          "markupSyntax": {
+            "enum": [
+              "MARKUP_SYNTAX_UNSPECIFIED",
+              "MARKUP_SYNTAX_CHAT",
+              "MARKUP_SYNTAX_MARKDOWN"
+            ],
+            "type": "string"
+          },
+          "matchedUrl": {
+            "properties": {
+              "url": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "name": {
+            "type": "string"
+          },
+          "privateMessageViewer": {
+            "properties": {
+              "avatarUrl": {
+                "type": "string"
+              },
+              "displayName": {
+                "type": "string"
+              },
+              "domainId": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string"
+              },
+              "isAnonymous": {
+                "type": "boolean"
+              },
+              "name": {
+                "type": "string"
+              },
+              "type": {
+                "enum": [
+                  "TYPE_UNSPECIFIED",
+                  "HUMAN",
+                  "BOT"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "quotedMessageMetadata": {
+            "properties": {
+              "forwardedMetadata": {
+                "properties": {
+                  "space": {
+                    "type": "string"
+                  },
+                  "spaceDisplayName": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "lastUpdateTime": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "quoteType": {
+                "enum": [
+                  "QUOTE_TYPE_UNSPECIFIED",
+                  "REPLY",
+                  "FORWARD"
+                ],
+                "type": "string"
+              },
+              "quotedMessageSnapshot": {
+                "properties": {
+                  "annotations": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "attachments": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "formattedText": {
+                    "type": "string"
+                  },
+                  "sender": {
+                    "type": "string"
+                  },
+                  "text": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "sender": {
+            "properties": {
+              "avatarUrl": {
+                "type": "string"
+              },
+              "displayName": {
+                "type": "string"
+              },
+              "domainId": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string"
+              },
+              "isAnonymous": {
+                "type": "boolean"
+              },
+              "name": {
+                "type": "string"
+              },
+              "type": {
+                "enum": [
+                  "TYPE_UNSPECIFIED",
+                  "HUMAN",
+                  "BOT"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "silent": {
+            "type": "boolean"
+          },
+          "slashCommand": {
+            "properties": {
+              "commandId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "space": {
+            "properties": {
+              "accessSettings": {
+                "properties": {
+                  "accessPermissionSettings": {
+                    "type": "object"
+                  },
+                  "accessState": {
+                    "enum": [
+                      "ACCESS_STATE_UNSPECIFIED",
+                      "PRIVATE",
+                      "DISCOVERABLE"
+                    ],
+                    "type": "string"
+                  },
+                  "audience": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "adminInstalled": {
+                "type": "boolean"
+              },
+              "createTime": {
+                "type": "string"
+              },
+              "customer": {
+                "type": "string"
+              },
+              "displayName": {
+                "type": "string"
+              },
+              "externalUserAllowed": {
+                "type": "boolean"
+              },
+              "importMode": {
+                "type": "boolean"
+              },
+              "importModeExpireTime": {
+                "type": "string"
+              },
+              "lastActiveTime": {
+                "type": "string"
+              },
+              "membershipCount": {
+                "properties": {
+                  "joinedDirectHumanUserCount": {
+                    "type": "integer"
+                  },
+                  "joinedGroupCount": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              },
+              "name": {
+                "type": "string"
+              },
+              "permissionSettings": {
+                "properties": {
+                  "manageApps": {
+                    "type": "object"
+                  },
+                  "manageMembersAndGroups": {
+                    "type": "object"
+                  },
+                  "manageWebhooks": {
+                    "type": "object"
+                  },
+                  "modifySpaceDetails": {
+                    "type": "object"
+                  },
+                  "postMessages": {
+                    "type": "object"
+                  },
+                  "replyMessages": {
+                    "type": "object"
+                  },
+                  "toggleHistory": {
+                    "type": "object"
+                  },
+                  "useAtMentionAll": {
+                    "type": "object"
+                  },
+                  "viewSpaceMembership": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "predefinedPermissionSettings": {
+                "enum": [
+                  "PREDEFINED_PERMISSION_SETTINGS_UNSPECIFIED",
+                  "COLLABORATION_SPACE",
+                  "ANNOUNCEMENT_SPACE"
+                ],
+                "type": "string"
+              },
+              "singleUserBotDm": {
+                "type": "boolean"
+              },
+              "spaceDetails": {
+                "properties": {
+                  "description": {
+                    "type": "string"
+                  },
+                  "guidelines": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "spaceHistoryState": {
+                "enum": [
+                  "HISTORY_STATE_UNSPECIFIED",
+                  "HISTORY_OFF",
+                  "HISTORY_ON"
+                ],
+                "type": "string"
+              },
+              "spaceThreadingState": {
+                "enum": [
+                  "SPACE_THREADING_STATE_UNSPECIFIED",
+                  "THREADED_MESSAGES",
+                  "GROUPED_MESSAGES",
+                  "UNTHREADED_MESSAGES"
+                ],
+                "type": "string"
+              },
+              "spaceType": {
+                "enum": [
+                  "SPACE_TYPE_UNSPECIFIED",
+                  "SPACE",
+                  "GROUP_CHAT",
+                  "DIRECT_MESSAGE"
+                ],
+                "type": "string"
+              },
+              "spaceUri": {
+                "type": "string"
+              },
+              "threaded": {
+                "type": "boolean"
+              },
+              "type": {
+                "enum": [
+                  "TYPE_UNSPECIFIED",
+                  "ROOM",
+                  "DM"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "text": {
+            "type": "string"
+          },
+          "thread": {
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "threadKey": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "threadReply": {
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "nextPageToken": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the caller must be a space member, that blocked members/spaces are included, that system messages are excluded, and that an empty space returns `{}`. However, the authentication section is truncated mid-sentence, leaving an important access requirement incompletely described.

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

Conciseness3/5

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

The purpose and edge-case behavior are front-loaded and useful, but the description also contains generic HTTP/body_file boilerplate and a truncated authentication bullet that reduce focus. The sibling list at the end is relevant context but is not integrated into actionable guidance.

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?

Given the full schema coverage, output schema, and 11 parameters, the description provides enough scope and edge-case context for an agent to call the tool correctly. The main omission is explicit comparison with the sibling `search` operation, but the core listing behavior is adequately covered.

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 coverage is 100%, so the schema already documents parameters such as `filter`, `pageSize`, `pageToken`, and `orderBy`. The description adds no parameter-level semantics beyond the schema, so the baseline 3 is appropriate.

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?

The description opens with a specific verb and resource: "Lists messages in a space that the caller is a member of," which is clear enough to distinguish this as a message-listing operation. It names sibling operations at the end, including "search," but does not explicitly explain how this differs from `chat.spaces.messages.search`.

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

Usage Guidelines2/5

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

The description states the membership prerequisite and notes that blocked members and system messages are handled in specific ways, but it never explicitly says when to use this tool versus `chat.spaces.messages.search` or other siblings. The trailing sibling list is context, not actionable routing guidance.

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

Deploy Server