feat(agent-toolkit): agents subgraph tools expansion

packages/agent-toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/agent-toolkit",
-  "version": "5.10.3",
+  "version": "5.11.0",
 
 
   "description": "monday.com agent toolkit",

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/create-agent/create-agent-tool.ts

@@ -80,7 +80,7 @@ Two modes:
 
 Do not mix prompt with manual profile fields in one request.
 
-Created agents start in state INACTIVE and must be activated before they can be triggered. Instruct the user to activate from the monday.com agent settings UI.
+Created agents start in state INACTIVE and must be activated before they can be triggered. After creation, call manage_agent_state with action:activate and the returned agent id.
 
 created_at and updated_at are null in the response — call get_agent with the returned id afterward to fetch them.
 
@@ -137,7 +137,7 @@ USAGE EXAMPLES:
 
         return {
           content: {
-            message: `monday platform agent ${res.create_blank_agent.id} created in state INACTIVE — user must activate it from the monday.com UI before it can be triggered`,
+            message: `monday platform agent ${res.create_blank_agent.id} created in state INACTIVE — call manage_agent_state with action:activate and agent_id:${res.create_blank_agent.id} to activate it`,
             agent: res.create_blank_agent,
           },
         };
@@ -163,12 +163,12 @@ USAGE EXAMPLES:
         throw new Error('monday platform agent creation returned no id');
       }
 
-      return {
-        content: {
-          message: `monday platform agent ${res.create_agent.id} created in state INACTIVE — user must activate it from the monday.com UI before it can be triggered`,
-          agent: res.create_agent,
-        },
-      };
+        return {
+          content: {
+            message: `monday platform agent ${res.create_agent.id} created in state INACTIVE — call manage_agent_state with action:activate and agent_id:${res.create_agent.id} to activate it`,
+            agent: res.create_agent,
+          },
+        };
     } catch (error) {
       rethrowWithContext(error, 'create monday platform agent');
     }

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/get-agent-catalog/get-agent-catalog-tool.test.ts

@@ -0,0 +1,108 @@
+import { MondayAgentToolkit } from 'src/mcp/toolkit';
+import { callToolByNameRawAsync, createMockApiClient, parseToolResult } from '../../test-utils/mock-api-client';
+import { GetAgentTriggersCatalogQuery, GetAgentSkillsCatalogQuery } from 'src/monday-graphql/generated/graphql.dev/graphql';
+
+describe('GetAgentCatalogTool', () => {
+  let mocks: ReturnType<typeof createMockApiClient>;
+
+  beforeEach(() => {
+    mocks = createMockApiClient();
+    jest.spyOn(MondayAgentToolkit.prototype as any, 'createApiClient').mockReturnValue(mocks.mockApiClient);
+  });
+
+  const mockTrigger = {
+    block_reference_id: 'status-change-ref',
+    name: 'Status Change',
+    description: 'Fires when a status column changes',
+    field_schemas: [{ field_key: 'board_id', value_schema: 'The ID of the board to watch' }],
+    required_fields: [{ field_key: 'board_id', depends_on: [], optional: false }],
+  };
+
+  const mockSkill = {
+    id: 'skill-1',
+    name: 'Board Manager',
+    description: 'Manages boards and items',
+  };
+
+  it('should return triggers catalog when type is triggers', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [mockTrigger] } as GetAgentTriggersCatalogQuery);
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.count).toBe(1);
+    expect(parsed.triggers[0].block_reference_id).toBe('status-change-ref');
+  });
+
+  it('should pass versionOverride dev when fetching triggers', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [] } as GetAgentTriggersCatalogQuery);
+
+    await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.stringContaining('getAgentTriggersCatalog'),
+      expect.objectContaining({ block_reference_ids: undefined }),
+      expect.objectContaining({ versionOverride: 'dev' }),
+    );
+  });
+
+  it('should pass block_reference_ids when provided', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [mockTrigger] } as GetAgentTriggersCatalogQuery);
+
+    await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers', block_reference_ids: ['status-change-ref'] });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ block_reference_ids: ['status-change-ref'] }),
+      expect.anything(),
+    );
+  });
+
+  it('should return skills catalog when type is skills', async () => {
+    mocks.setResponseOnce({ agent_skills_catalog: [mockSkill] } as GetAgentSkillsCatalogQuery);
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'skills' });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.count).toBe(1);
+    expect(parsed.skills[0].id).toBe('skill-1');
+  });
+
+  it('should pass versionOverride dev when fetching skills', async () => {
+    mocks.setResponseOnce({ agent_skills_catalog: [] } as GetAgentSkillsCatalogQuery);
+
+    await callToolByNameRawAsync('get_agent_catalog', { type: 'skills' });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.stringContaining('getAgentSkillsCatalog'),
+      expect.anything(),
+      expect.objectContaining({ versionOverride: 'dev' }),
+    );
+  });
+
+  it('should return empty list with count 0 when no triggers exist', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [] } as GetAgentTriggersCatalogQuery);
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.count).toBe(0);
+    expect(parsed.triggers).toEqual([]);
+  });
+
+  it('should propagate errors when fetching triggers catalog', async () => {
+    mocks.setError('Unauthorized');
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+
+    expect(result.content[0].text).toContain('Failed to fetch monday platform agent triggers catalog');
+  });
+
+  it('should propagate errors when fetching skills catalog', async () => {
+    mocks.setError('Unauthorized');
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'skills' });
+
+    expect(result.content[0].text).toContain('Failed to fetch monday platform agent skills catalog');
+  });
+});

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/get-agent-catalog/get-agent-catalog-tool.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import {
+  GetAgentTriggersCatalogQuery,
+  GetAgentTriggersCatalogQueryVariables,
+  GetAgentSkillsCatalogQuery,
+} from '../../../../../monday-graphql/generated/graphql.dev/graphql';
+import { getAgentTriggersCatalogQuery, getAgentSkillsCatalogQuery } from './get-agent-catalog.graphql.dev';
+import { ToolInputType, ToolOutputType, ToolType } from '../../../../tool';
+import { BaseMondayApiTool, createMondayApiAnnotations } from '../../base-monday-api-tool';
+import { rethrowWithContext } from '../../../../../utils';
+
+export const getAgentCatalogToolSchema = {
+  type: z
+    .enum(['triggers', 'skills'])
+    .describe(
+      'Which catalog to fetch. "triggers" returns available trigger types with block_reference_id, field_schemas, and required_fields — use before calling manage_agent_triggers with action:add. "skills" returns available skills with id — use before calling manage_agent_skills.',
+    ),
+  block_reference_ids: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Only applies when type is "triggers". Fetch specific entries by block_reference_id instead of the full catalog. Omit to return all trigger types.',
+    ),
+};
+
+export class GetAgentCatalogTool extends BaseMondayApiTool<typeof getAgentCatalogToolSchema> {
+  name = 'get_agent_catalog';
+  type = ToolType.READ;
+  annotations = createMondayApiAnnotations({
+    title: 'Get monday Platform Agent Catalog',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+  });
+
+  getDescription(): string {
+    return `Fetch the account-wide catalog of available trigger types or skills for monday platform agents.
+
+ALWAYS call this tool first before adding a trigger or skill to an agent:
+- type:"triggers" — returns entries with block_reference_id (required for manage_agent_triggers action:add), name, description, field_schemas (describes the field_values shape to pass when adding — e.g. { board_id: "<ID>" }), and required_fields (fields the user must supply before you can call add).
+- type:"skills" — returns entries with id (required for manage_agent_skills), name, description.
+
+Never guess or invent a block_reference_id or skill id — always look them up here first.
+
+USAGE EXAMPLES:
+- List all trigger types: { "type": "triggers" }
+- Fetch a specific trigger type: { "type": "triggers", "block_reference_ids": ["some-block-ref-id"] }
+- List all skills: { "type": "skills" }`;
+  }
+
+  getInputSchema() {
+    return getAgentCatalogToolSchema;
+  }
+
+  protected async executeInternal(
+    input: ToolInputType<typeof getAgentCatalogToolSchema>,
+  ): Promise<ToolOutputType<never>> {
+    if (input.type === 'triggers') {
+      try {
+        const variables: GetAgentTriggersCatalogQueryVariables = {
+          block_reference_ids: input.block_reference_ids,
+        };
+        const res = await this.mondayApi.request<GetAgentTriggersCatalogQuery>(
+          getAgentTriggersCatalogQuery,
+          variables,
+          { versionOverride: 'dev' },
+        );
+        const catalog = res.agent_triggers_catalog ?? [];
+        return {
+          content: {
+            message:
+              'Available trigger types for monday platform agents. Use block_reference_id and inspect field_schemas/required_fields before calling manage_agent_triggers with action:add.',
+            count: catalog.length,
+            triggers: catalog,
+          },
+        };
+      } catch (error) {
+        rethrowWithContext(error, 'fetch monday platform agent triggers catalog');
+      }
+    }
+
+    try {
+      const res = await this.mondayApi.request<GetAgentSkillsCatalogQuery>(
+        getAgentSkillsCatalogQuery,
+        {},
+        { versionOverride: 'dev' },
+      );
+      const catalog = res.agent_skills_catalog ?? [];
+      return {
+        content: {
+          message: 'Available skills for monday platform agents. Use id when calling manage_agent_skills.',
+          count: catalog.length,
+          skills: catalog,
+        },
+      };
+    } catch (error) {
+      rethrowWithContext(error, 'fetch monday platform agent skills catalog');
+    }
+  }
+}

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/get-agent-catalog/get-agent-catalog.graphql.dev.ts

@@ -0,0 +1,30 @@
+import { gql } from 'graphql-request';
+
+export const getAgentTriggersCatalogQuery = gql`
+  query getAgentTriggersCatalog($block_reference_ids: [ID!]) {
+    agent_triggers_catalog(block_reference_ids: $block_reference_ids) {
+      block_reference_id
+      name
+      description
+      field_schemas {
+        field_key
+        value_schema
+      }
+      required_fields {
+        field_key
+        depends_on
+        optional
+      }
+    }
+  }
+`;
+
+export const getAgentSkillsCatalogQuery = gql`
+  query getAgentSkillsCatalog {
+    agent_skills_catalog {
+      id
+      name
+      description
+    }
+  }
+`;

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/index.ts

@@ -1,3 +1,9 @@
 export * from './get-agent/get-agent-tool';
 export * from './create-agent/create-agent-tool';
 export * from './delete-agent/delete-agent-tool';
+export * from './get-agent-catalog/get-agent-catalog-tool';
+export * from './manage-agent-triggers/manage-agent-triggers-tool';
+export * from './manage-agent-skills/manage-agent-skills-tool';
+export * from './update-agent/update-agent-tool';
+export * from './manage-agent-state/manage-agent-state-tool';
+export * from './manage-agent-knowledge/manage-agent-knowledge-tool';