feat(agent-toolkit): document the "group" filter column

packages/agent-toolkit/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 5.68.0
+
+### Make the "group" filter column discoverable
+
+Filtering items by board group has always worked - `filters: [{"columnId": "group", "compareValue": ["group_mm6wsvcc"]}]` - but it was documented nowhere: not in the tool description, not in the input schema, and `get_board_info` does not return `group` among a board's columns. Models could only get it right from prior knowledge of the monday API.
+
+This produced 21% of `get_board_items_page`'s `ResourceNotFoundException` errors across 191 accounts: `includeGroup` hands the model each item's `group.id`, and with no documented way to filter on it, models put the group id in `filters[].columnId` and got "Column not found". In 81% of those cases the model then abandoned filtering and paged through the whole board.
+
+Descriptions only, no filtering behavior or schema-shape change:
+
+- `get_board_items_page` description gains a GROUP FILTERING section with the exact filter rule to use, and states that a group id is never a valid `columnId`.
+- `filters[].columnId` states that `group` is accepted alongside real board column ids.
+- `get_column_type_info` returns filter guidelines for `columnType: "group"`, which previously returned `filter: null` even though `group` is a member of the column-type enum.
+
 ## 5.67.0
 
 ### get_user_context — include relevant docs

packages/agent-toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/agent-toolkit",
-  "version": "5.67.0",
+  "version": "5.68.0",
   "description": "monday.com agent toolkit",
   "exports": {
     "./mcp": {

packages/agent-toolkit/src/core/tools/platform-api-tools/get-board-items-page-tool/get-board-items-page-tool.ts

@@ -161,6 +161,7 @@ export class GetBoardItemsPageTool extends BaseMondayApiTool<GetBoardItemsPageTo
       'To retrieve an item description (the rich-text body/details of a monday.com item), set includeItemDescription to true — the response will include the item description document blocks with their content, type, and id. Use this whenever the user asks about an item description, body, details, or notes. ' +
       '[MULTI-LEVEL BOARDS]: The response includes hierarchy_type on the board ("multi_level" for MLS boards) and parent_item_id on each item. On multi-level boards, items form a tree (up to 5 levels). Use includeSubItems to get all descendants (returned flat with parent_item_id to reconstruct the tree). Top-level items have no parent_item_id. Subitems reference their parent. ' +
       '[REQUIRED PRECONDITION]: Before using this tool, if new columns were added to the board or if you are not familiar with the board structure (column IDs, column types, status labels, etc.), first use get_board_info with filters.columns.only to get column metadata without fetching views. This is essential for constructing proper filters and knowing which columns are available. ' +
+      '[GROUP FILTERING]: To get only the items of one board group, add a filter rule with columnId "group" and the group id as compareValue, e.g. filters: [{"columnId": "group", "compareValue": ["group_mm6wsvcc"]}]. Group ids come from an item\'s group.id or from get_board_info. A group id is never a valid columnId. ' +
       '[REQUIRED PRECONDITION]: For board-relation / cross-board linking tasks, call link_board_items_workflow before using this tool. ' +
       'VIEW-BASED FILTERING: If the user refers to a board view by name (e.g. "show me items in the Overdue view"), first call get_board_info with filters.views.names set to that view name (avoids downloading all views on large boards), extract the matching view\'s filter field, then pass it as the filters argument here.'
     );

packages/agent-toolkit/src/core/tools/platform-api-tools/get-board-items-page-tool/items-filter-schema.ts

@@ -16,7 +16,11 @@ import {
 export const filterRulesSchema = z
   .array(
     z.object({
-      columnId: z.string().describe('The id of the column to filter by'),
+      columnId: z
+        .string()
+        .describe(
+          'The id of the column to filter by. One non-column id is also accepted: "group", which filters by board group and takes the group id (e.g. "group_mm6wsvcc") as its compareValue. A group id is never a valid columnId itself.',
+        ),
       compareAttribute: z
         .string()
         .optional()

packages/agent-toolkit/src/core/tools/platform-api-tools/utils/column-filter-aggregation-guidelines.ts

@@ -1,6 +1,13 @@
 import { AggregateSelectFunctionName } from '../../../../monday-graphql/generated/graphql/graphql';
 
 export const filteringGuidelinesByColumnType: Record<string, string> = {
+  group: `Filters items by the board group they belong to. The columnId is the literal string "group" - a group id such as "group_mm6wsvcc" is NEVER a valid columnId. For filtering by group id, use any_of or not_any_of. Use an array of group ids, as returned in an item's group.id or by get_board_info.
+EXAMPLES:
+  ✅ Correct: {"columnId": "group", "compareValue": ["group_mm6wsvcc"], "operator": "any_of"} // group id goes in compareValue
+  ✅ Correct: {"columnId": "group", "compareValue": ["group_mm6wsvcc", "group_mm4w1e0n"], "operator": "any_of"} // several groups
+  ❌ Wrong: {"columnId": "group_mm6wsvcc", "compareValue": "group_mm6wsvcc"} // group id used as the columnId
+  ❌ Wrong: {"columnId": "group", "compareValue": "Backlog", "operator": "any_of"} // group title instead of group id`,
+
   last_updated: `Supported operators: any_of, not_any_of. CompareValue should be either:
   - "TODAY" - requires to also specify compareAttribute: "UPDATED_AT"
   - "YESTERDAY" - requires to also specify compareAttribute: "UPDATED_AT"