Skip to content

The open alternative to Salesforce, designed for AI.

Migrate the metadata tools to @DefineTool (#28631)

Paul Rastoin925304d2f093
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/2-52-upgrade-version-command.module.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/2-52-upgrade-version-command.module.ts
new file mode 100644
index 00000000000..4066b3cc6be
--- /dev/null
+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/2-52-upgrade-version-command.module.ts
@@ -0,0 +1,18 @@
+import { Module } from '@nestjs/common';
+
+import { WorkspaceIteratorModule } from 'src/database/commands/command-runners/workspace-iterator.module';
+import { ReconcileStandardSkillCatalogCommand } from 'src/database/commands/upgrade-version-command/2-52/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command';
+import { ApplicationModule } from 'src/engine/core-modules/application/application.module';
+import { WorkspaceCacheModule } from 'src/engine/workspace-cache/workspace-cache.module';
+import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace-migration/workspace-migration.module';
+
+@Module({
+ imports: [
+ ApplicationModule,
+ WorkspaceCacheModule,
+ WorkspaceIteratorModule,
+ WorkspaceMigrationModule,
+ ],
+ providers: [ReconcileStandardSkillCatalogCommand],
+})
+export class V2_52_UpgradeVersionCommandModule {}
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command.ts
new file mode 100644
index 00000000000..b6d92494693
--- /dev/null
+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command.ts
@@ -0,0 +1,194 @@
+import { Command } from 'nest-commander';
+import { TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER } from 'twenty-shared/application';
+import { isDefined } from 'twenty-shared/utils';
+
+import { ProvisionedWorkspaceCommandRunner } from 'src/database/commands/command-runners/provisioned-workspace.command-runner';
+import { WorkspaceIteratorService } from 'src/database/commands/command-runners/workspace-iterator.service';
+import { type RunOnWorkspaceArgs } from 'src/database/commands/command-runners/workspace.command-runner';
+import { ApplicationService } from 'src/engine/core-modules/application/application.service';
+import { RegisteredWorkspaceCommand } from 'src/engine/core-modules/upgrade/decorators/registered-workspace-command.decorator';
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';
+import { computeTwentyStandardApplicationAllFlatEntityMaps } from 'src/engine/workspace-manager/twenty-standard-application/utils/twenty-standard-application-all-flat-entity-maps.constant';
+import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
+import { WorkspaceMigrationValidateBuildAndRunService } from 'src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service';
+
+@RegisteredWorkspaceCommand('2.52.0', 1792764632845)
+@Command({
+ name: 'upgrade:2-52:reconcile-standard-skill-catalog',
+ description:
+ 'Reconcile the standard skill catalog in existing workspaces again, so the skill content changed since 2.40 reaches them: create the new skills, refresh the catalog-owned fields on existing ones, and delete the skills that left the catalog',
+})
+export class ReconcileStandardSkillCatalogCommand extends ProvisionedWorkspaceCommandRunner {
+ constructor(
+ protected readonly workspaceIteratorService: WorkspaceIteratorService,
+ private readonly applicationService: ApplicationService,
+ private readonly workspaceMigrationValidateBuildAndRunService: WorkspaceMigrationValidateBuildAndRunService,
+ private readonly workspaceCacheService: WorkspaceCacheService,
+ ) {
+ super(workspaceIteratorService);
+ }
+
+ override async runOnWorkspace(args: RunOnWorkspaceArgs): Promise<void> {
+ await this.up(args);
+ }
+
+ async up({ workspaceId, options }: RunOnWorkspaceArgs): Promise<void> {
+ const isDryRun = options.dryRun ?? false;
+
+ const { twentyStandardFlatApplication } =
+ await this.applicationService.findWorkspaceTwentyStandardAndCustomApplicationOrThrow(
+ { workspaceId },
+ );
+
+ const { flatSkillMaps: existingFlatSkillMaps } =
+ await this.workspaceCacheService.getOrRecompute(workspaceId, [
+ 'flatSkillMaps',
+ ]);
+
+ const { allFlatEntityMaps: standardAllFlatEntityMaps } =
+ computeTwentyStandardApplicationAllFlatEntityMaps({
+ now: new Date().toISOString(),
+ workspaceId,
+ twentyStandardApplicationId: twentyStandardFlatApplication.id,
+ });
+
+ const standardSkills = Object.values(
+ standardAllFlatEntityMaps.flatSkillMaps.byUniversalIdentifier,
+ ).filter(isDefined);
+
+ const existingSkills = Object.values(
+ existingFlatSkillMaps.byUniversalIdentifier,
+ ).filter(isDefined);
+
+ const standardSkillUniversalIdentifiers = new Set(
+ standardSkills.map((standardSkill) => standardSkill.universalIdentifier),
+ );
+
+ const skillsToDelete = existingSkills.filter(
+ (existingSkill) =>
+ existingSkill.applicationId === twentyStandardFlatApplication.id &&
+ !standardSkillUniversalIdentifiers.has(
+ existingSkill.universalIdentifier,
+ ),
+ );
+
+ const universalIdentifiersToDelete = new Set(
+ skillsToDelete.map((skillToDelete) => skillToDelete.universalIdentifier),
+ );
+
+ // Skill names are unique per workspace, and one rejected create would fail the whole migration
+ const takenNames = new Set(
+ existingSkills
+ .filter(
+ (existingSkill) =>
+ !universalIdentifiersToDelete.has(existingSkill.universalIdentifier),
+ )
+ .map((existingSkill) => existingSkill.name),
+ );
+
+ const missingSkills = standardSkills.filter(
+ (standardSkill) =>
+ !isDefined(
+ existingFlatSkillMaps.byUniversalIdentifier[
+ standardSkill.universalIdentifier
+ ],
+ ),
+ );
+
+ const skillsToCreate = missingSkills.filter(
+ (missingSkill) => !takenNames.has(missingSkill.name),
+ );
+
+ const skillsSkippedForNameClash = missingSkills.filter((missingSkill) =>
+ takenNames.has(missingSkill.name),
+ );
+
+ if (skillsSkippedForNameClash.length > 0) {
+ this.logger.warn(
+ `Workspace ${workspaceId} already has a skill named ${skillsSkippedForNameClash.map((skill) => skill.name).join(', ')}; skipping ${skillsSkippedForNameClash.length === 1 ? 'that standard skill' : 'those standard skills'}`,
+ );
+ }
+
+ const skillsToUpdate = standardSkills.reduce<FlatSkill[]>(
+ (accumulator, standardSkill) => {
+ const existingSkill =
+ existingFlatSkillMaps.byUniversalIdentifier[
+ standardSkill.universalIdentifier
+ ];
+
+ if (!isDefined(existingSkill)) {
+ return accumulator;
+ }
+
+ const hasCatalogChange =
+ existingSkill.isSystem !== standardSkill.isSystem ||
+ existingSkill.label !== standardSkill.label ||
+ existingSkill.description !== standardSkill.description ||
+ existingSkill.icon !== standardSkill.icon ||
+ existingSkill.content !== standardSkill.content;
+
+ if (!hasCatalogChange) {
+ return accumulator;
+ }
+
+ // isActive is the user's call, so the refresh must not reactivate a skill someone turned off
+ accumulator.push({
+ ...existingSkill,
+ isSystem: standardSkill.isSystem,
+ label: standardSkill.label,
+ description: standardSkill.description,
+ icon: standardSkill.icon,
+ content: standardSkill.content,
+ });
+
+ return accumulator;
+ },
+ [],
+ );
+
+ if (
+ skillsToCreate.length === 0 &&
+ skillsToUpdate.length === 0 &&
+ skillsToDelete.length === 0
+ ) {
+ this.logger.log(
+ `Standard skills already up to date for workspace ${workspaceId}, skipping`,
+ );
+
+ return;
+ }
+
+ this.logger.log(
+ `${isDryRun ? '[DRY RUN] ' : ''}Workspace ${workspaceId}: creating ${skillsToCreate.length}, updating ${skillsToUpdate.length}, deleting ${skillsToDelete.length} standard skill(s)`,
+ );
+
+ if (isDryRun) {
+ return;
+ }
+
+ const result =
+ await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunLegacyWorkspaceMigration(
+ {
+ workspaceId,
+ isSystemBuild: true,
+ applicationUniversalIdentifier:
+ TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER,
+ allFlatEntityOperationByMetadataName: {
+ skill: {
+ flatEntityToCreate: skillsToCreate,
+ flatEntityToDelete: skillsToDelete,
+ flatEntityToUpdate: skillsToUpdate,
+ },
+ },
+ },
+ );
+
+ if (result.status === 'fail') {
+ throw new WorkspaceMigrationBuilderException(
+ result,
+ `Failed to reconcile the standard skill catalog for workspace ${workspaceId}`,
+ );
+ }
+ }
+}
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/__tests__/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command.spec.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/__tests__/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command.spec.ts
new file mode 100644
index 00000000000..dbb62a7a85b
--- /dev/null
+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-52/__tests__/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command.spec.ts
@@ -0,0 +1,255 @@
+import { TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER } from 'twenty-shared/application';
+import { isDefined } from 'twenty-shared/utils';
+
+import { type WorkspaceIteratorService } from 'src/database/commands/command-runners/workspace-iterator.service';
+import { ReconcileStandardSkillCatalogCommand } from 'src/database/commands/upgrade-version-command/2-52/2-52-workspace-command-1792764632845-reconcile-standard-skill-catalog.command';
+import { type ApplicationService } from 'src/engine/core-modules/application/application.service';
+import { type WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';
+import { computeTwentyStandardApplicationAllFlatEntityMaps } from 'src/engine/workspace-manager/twenty-standard-application/utils/twenty-standard-application-all-flat-entity-maps.constant';
+import { type WorkspaceMigrationValidateBuildAndRunService } from 'src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service';
+
+const WORKSPACE_ID = '20202020-0000-0000-0000-000000000001';
+const STANDARD_APPLICATION_ID = '20202020-0000-0000-0000-0000000000a1';
+const OTHER_APPLICATION_ID = '20202020-0000-0000-0000-0000000000b2';
+
+// The catalog these tests reconcile against is the real one, so they stay honest when it changes
+const RETIRED_SKILL_UNIVERSAL_IDENTIFIER =
+ '20202020-6b44-417e-a31f-5560b59d300a';
+const METADATA_BUILDING_UNIVERSAL_IDENTIFIER =
+ '20202020-7b80-4a14-8fb9-d1512b89c078';
+
+type ExistingSkill = {
+ id: string;
+ universalIdentifier: string;
+ applicationId: string;
+ workspaceId: string;
+ name: string;
+ label: string;
+ description: string;
+ icon: string;
+ content: string;
+ isCustom: boolean;
+ isSystem: boolean;
+ isActive: boolean;
+};
+
+const buildExistingSkill = ({
+ universalIdentifier,
+ applicationId = STANDARD_APPLICATION_ID,
+ isSystem = false,
+ isActive = true,
+ content = 'content',
+ name,
+}: {
+ universalIdentifier: string;
+ applicationId?: string;
+ isSystem?: boolean;
+ isActive?: boolean;
+ content?: string;
+ name?: string;
+}): ExistingSkill => ({
+ id: `id-${universalIdentifier}`,
+ universalIdentifier,
+ applicationId,
+ workspaceId: WORKSPACE_ID,
+ name: name ?? `name-${universalIdentifier}`,
+ label: `label-${universalIdentifier}`,
+ description: 'description',
+ icon: 'IconBook',
+ content,
+ isCustom: false,
+ isSystem,
+ isActive,
+});
+
+const buildStandardFlatSkills = () =>
+ Object.values(
+ computeTwentyStandardApplicationAllFlatEntityMaps({
+ now: new Date().toISOString(),
+ workspaceId: WORKSPACE_ID,
+ twentyStandardApplicationId: STANDARD_APPLICATION_ID,
+ }).allFlatEntityMaps.flatSkillMaps.byUniversalIdentifier,
+ ).filter(isDefined);
+
+const runCommand = async ({
+ existingSkills,
+ dryRun = false,
+}: {
+ existingSkills: ExistingSkill[];
+ dryRun?: boolean;
+}) => {
+ const validateBuildAndRunLegacyWorkspaceMigration = jest
+ .fn()
+ .mockResolvedValue({ status: 'success' });
+
+ const command = new ReconcileStandardSkillCatalogCommand(
+ {} as WorkspaceIteratorService,
+ {
+ findWorkspaceTwentyStandardAndCustomApplicationOrThrow: jest
+ .fn()
+ .mockResolvedValue({
+ twentyStandardFlatApplication: {
+ id: STANDARD_APPLICATION_ID,
+ universalIdentifier: TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER,
+ },
+ }),
+ } as unknown as ApplicationService,
+ {
+ validateBuildAndRunLegacyWorkspaceMigration,
+ } as unknown as WorkspaceMigrationValidateBuildAndRunService,
+ {
+ getOrRecompute: jest.fn().mockResolvedValue({
+ flatSkillMaps: {
+ byUniversalIdentifier: Object.fromEntries(
+ existingSkills.map((skill) => [skill.universalIdentifier, skill]),
+ ),
+ },
+ }),
+ } as unknown as WorkspaceCacheService,
+ );
+
+ await command.runOnWorkspace({
+ workspaceId: WORKSPACE_ID,
+ options: { dryRun },
+ } as Parameters<typeof command.runOnWorkspace>[0]);
+
+ const [migrationArgs] =
+ validateBuildAndRunLegacyWorkspaceMigration.mock.calls[0] ?? [];
+
+ return {
+ validateBuildAndRunLegacyWorkspaceMigration,
+ migrationArgs,
+ skillOperation: migrationArgs?.allFlatEntityOperationByMetadataName.skill,
+ };
+};
+
+describe('ReconcileStandardSkillCatalogCommand', () => {
+ it('refreshes the content of a standard skill that changed, without reactivating it', async () => {
+ const { skillOperation } = await runCommand({
+ existingSkills: [
+ buildExistingSkill({
+ universalIdentifier: METADATA_BUILDING_UNIVERSAL_IDENTIFIER,
+ isSystem: true,
+ isActive: false,
+ content: 'get_object_metadata returns an array of objects.',
+ }),
+ ],
+ });
+
+ const updatedSkill = skillOperation?.flatEntityToUpdate.find(
+ (skill: ExistingSkill) =>
+ skill.universalIdentifier === METADATA_BUILDING_UNIVERSAL_IDENTIFIER,
+ );
+
+ expect(updatedSkill).toMatchObject({
+ id: `id-${METADATA_BUILDING_UNIVERSAL_IDENTIFIER}`,
+ isActive: false,
+ });
+ expect(updatedSkill?.content).toContain('result.objects');
+ });
+
+ it('applies the migration as the twenty standard application', async () => {
+ const { migrationArgs } = await runCommand({ existingSkills: [] });
+
+ expect(migrationArgs).toMatchObject({
+ workspaceId: WORKSPACE_ID,
+ isSystemBuild: true,
+ applicationUniversalIdentifier:
+ TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER,
+ });
+ });
+
+ it('creates the standard skills the workspace does not have yet', async () => {
+ const { skillOperation } = await runCommand({ existingSkills: [] });
+
+ expect(
+ skillOperation?.flatEntityToCreate.map(
+ (skill: ExistingSkill) => skill.name,
+ ),
+ ).toEqual(
+ expect.arrayContaining(['metadata-building', 'enrich', 'meeting-prep']),
+ );
+ });
+
+ it('deletes a standard skill that left the catalog', async () => {
+ const { skillOperation } = await runCommand({
+ existingSkills: [
+ buildExistingSkill({
+ universalIdentifier: RETIRED_SKILL_UNIVERSAL_IDENTIFIER,
+ }),
+ ],
+ });
+
+ expect(
+ skillOperation?.flatEntityToDelete.map(
+ (skill: ExistingSkill) => skill.universalIdentifier,
+ ),
+ ).toEqual([RETIRED_SKILL_UNIVERSAL_IDENTIFIER]);
+ });
+
+ it('leaves skills owned by another application alone', async () => {
+ const { skillOperation } = await runCommand({
+ existingSkills: [
+ buildExistingSkill({
+ universalIdentifier: RETIRED_SKILL_UNIVERSAL_IDENTIFIER,
+ applicationId: OTHER_APPLICATION_ID,
+ }),
+ ],
+ });
+
+ expect(skillOperation?.flatEntityToDelete).toEqual([]);
+ });
+
+ it('skips a create whose name another skill already took', async () => {
+ const { skillOperation } = await runCommand({
+ existingSkills: [
+ buildExistingSkill({
+ universalIdentifier: '20202020-0000-0000-0000-00000000c0de',
+ applicationId: OTHER_APPLICATION_ID,
+ name: 'enrich',
+ }),
+ ],
+ });
+
+ const createdNames = skillOperation?.flatEntityToCreate.map(
+ (skill: ExistingSkill) => skill.name,
+ );
+
+ expect(createdNames).not.toContain('enrich');
+ expect(createdNames).toContain('meeting-prep');
+ });
+
+ it('still creates a standard skill whose name is only held by a skill being deleted', async () => {
+ const { skillOperation } = await runCommand({
+ existingSkills: [
+ buildExistingSkill({
+ universalIdentifier: RETIRED_SKILL_UNIVERSAL_IDENTIFIER,
+ name: 'enrich',
+ }),
+ ],
+ });
+
+ expect(
+ skillOperation?.flatEntityToCreate.map(
+ (skill: ExistingSkill) => skill.name,
+ ),
+ ).toContain('enrich');
+ });
+
+ it('queues no migration when the workspace already matches the catalog', async () => {
+ const { validateBuildAndRunLegacyWorkspaceMigration } = await runCommand({
+ existingSkills: buildStandardFlatSkills() as unknown as ExistingSkill[],
+ });
+
+ expect(validateBuildAndRunLegacyWorkspaceMigration).not.toHaveBeenCalled();
+ });
+
+ it('queues no migration in dry run', async () => {
+ const { validateBuildAndRunLegacyWorkspaceMigration } = await runCommand({
+ existingSkills: [],
+ dryRun: true,
+ });
+
+ expect(validateBuildAndRunLegacyWorkspaceMigration).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/workspace-command-provider.module.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/workspace-command-provider.module.ts
index 8c6dc30c3ee..4932f6d665f 100644
--- a/packages/twenty-server/src/database/commands/upgrade-version-command/workspace-command-provider.module.ts
+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/workspace-command-provider.module.ts
@@ -44,6 +44,7 @@ import { V2_48_UpgradeVersionCommandModule } from 'src/database/commands/upgrade
import { V2_49_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-49/2-49-upgrade-version-command.module';
import { V2_50_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-50/2-50-upgrade-version-command.module';
import { V2_51_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-51/2-51-upgrade-version-command.module';
+import { V2_52_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-52/2-52-upgrade-version-command.module';
import { V2_4_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-4/2-4-upgrade-version-command.module';
import { V2_5_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-5/2-5-upgrade-version-command.module';
import { V2_7_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-version-command/2-7/2-7-upgrade-version-command.module';
@@ -101,6 +102,7 @@ import { V2_9_UpgradeVersionCommandModule } from 'src/database/commands/upgrade-
V2_49_UpgradeVersionCommandModule,
V2_50_UpgradeVersionCommandModule,
V2_51_UpgradeVersionCommandModule,
+ V2_52_UpgradeVersionCommandModule,
],
})
export class WorkspaceCommandProviderModule {}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/metadata-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/metadata-tool.provider.ts
deleted file mode 100644
index 8393d67f340..00000000000
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/metadata-tool.provider.ts
+++ /dev/null
@@ -1,85 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-import { PermissionFlagType } from 'twenty-shared/constants';
-import { FeatureFlagKey } from 'twenty-shared/types';
-
-import { FeatureFlagService } from 'src/engine/core-modules/feature-flag/services/feature-flag.service';
-import { type GenerateDescriptorOptions } from 'src/engine/core-modules/tool-provider/interfaces/generate-descriptor-options.type';
-import { type ToolProvider } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider.interface';
-import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
-
-import { ToolCategory } from 'twenty-shared/ai';
-import { type ToolDescriptor } from 'src/engine/core-modules/tool-provider/types/tool-descriptor.type';
-import { type ToolIndexEntry } from 'src/engine/core-modules/tool-provider/types/tool-index-entry.type';
-import { executeToolFromToolSet } from 'src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util';
-import { toolSetToDescriptors } from 'src/engine/core-modules/tool-provider/utils/tool-set-to-descriptors.util';
-import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
-import { FieldMetadataToolsFactory } from 'src/engine/metadata-modules/field-metadata/tools/field-metadata-tools.factory';
-import { ObjectMetadataToolsFactory } from 'src/engine/metadata-modules/object-metadata/tools/object-metadata-tools.factory';
-import { PermissionsService } from 'src/engine/metadata-modules/permissions/permissions.service';
-import { ValidationRuleToolsFactory } from 'src/engine/metadata-modules/validation-rule/tools/validation-rule-tools.factory';
-
-@Injectable()
-export class MetadataToolProvider implements ToolProvider {
- readonly category = ToolCategory.METADATA;
-
- constructor(
- private readonly objectMetadataToolsFactory: ObjectMetadataToolsFactory,
- private readonly fieldMetadataToolsFactory: FieldMetadataToolsFactory,
- private readonly validationRuleToolsFactory: ValidationRuleToolsFactory,
- private readonly permissionsService: PermissionsService,
- private readonly featureFlagService: FeatureFlagService,
- ) {}
-
- async isAvailable(context: ToolProviderContext): Promise<boolean> {
- return this.permissionsService.checkRolesPermissions(
- context.rolePermissionConfig,
- context.workspaceId,
- PermissionFlagType.DATA_MODEL,
- );
- }
-
- async generateDescriptors(
- context: ToolProviderContext,
- options?: GenerateDescriptorOptions,
- ): Promise<(ToolIndexEntry | ToolDescriptor)[]> {
- const toolSet = await this.buildToolSet(context);
-
- return toolSetToDescriptors(toolSet, ToolCategory.METADATA, {
- includeSchemas: options?.includeSchemas ?? true,
- icon: 'IconSettings',
- });
- }
-
- async executeStaticTool(
- toolName: string,
- args: Record<string, unknown>,
- context: ToolProviderContext,
- ): Promise<ToolOutput> {
- const toolSet = await this.buildToolSet(context);
-
- return executeToolFromToolSet(
- toolSet,
- toolName,
- args,
- ToolCategory.METADATA,
- );
- }
-
- private async buildToolSet(context: ToolProviderContext): Promise<ToolSet> {
- const isRecordCreationFormEnabled =
- await this.featureFlagService.isFeatureEnabled(
- FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
- context.workspaceId,
- );
-
- return {
- ...this.objectMetadataToolsFactory.generateTools(context.workspaceId),
- ...this.fieldMetadataToolsFactory.generateTools(context.workspaceId),
- ...(isRecordCreationFormEnabled
- ? this.validationRuleToolsFactory.generateTools(context.workspaceId)
- : {}),
- };
- }
-}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
index 78e7c2a2cb8..311ec5c44e8 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
@@ -11,7 +11,6 @@ import { ActionToolProvider } from 'src/engine/core-modules/tool-provider/provid
import { DashboardToolProvider } from 'src/engine/core-modules/tool-provider/providers/dashboard-tool.provider';
import { DatabaseToolProvider } from 'src/engine/core-modules/tool-provider/providers/database-tool.provider';
import { LogicFunctionToolProvider } from 'src/engine/core-modules/tool-provider/providers/logic-function-tool.provider';
-import { MetadataToolProvider } from 'src/engine/core-modules/tool-provider/providers/metadata-tool.provider';
import { WorkflowToolProvider } from 'src/engine/core-modules/tool-provider/providers/workflow-tool.provider';
import { DefinedToolRegistryService } from 'src/engine/core-modules/tool-provider/services/defined-tool-registry.service';
import { RecordFilesResolverService } from 'src/engine/core-modules/tool-provider/services/record-files-resolver.service';
@@ -20,14 +19,12 @@ import { ToolModule } from 'src/engine/core-modules/tool/tool.module';
import { UserEntity } from 'src/engine/core-modules/user/user.entity';
import { AgentToolsModule } from 'src/engine/metadata-modules/ai/ai-agent/tools/agent-tools.module';
import { ApplicationTranslationCatalogModule } from 'src/engine/metadata-modules/application-translation-catalog/application-translation-catalog.module';
-import { FieldMetadataModule } from 'src/engine/metadata-modules/field-metadata/field-metadata.module';
import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
import { NavigationMenuItemToolsModule } from 'src/engine/metadata-modules/navigation-menu-item/tools/navigation-menu-item-tools.module';
-import { ObjectMetadataModule } from 'src/engine/metadata-modules/object-metadata/object-metadata.module';
+import { MetadataToolsModule } from 'src/engine/metadata-modules/object-metadata/tools/metadata-tools.module';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
import { RoleToolsModule } from 'src/engine/metadata-modules/role/tools/role-tools.module';
import { UserRoleModule } from 'src/engine/metadata-modules/user-role/user-role.module';
-import { ValidationRuleModule } from 'src/engine/metadata-modules/validation-rule/validation-rule.module';
import { ViewToolsModule } from 'src/engine/metadata-modules/view/tools/view-tools.module';
import { WebhookToolsModule } from 'src/engine/metadata-modules/webhook/tools/webhook-tools.module';
import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/provide-workspace-scoped-repository';
@@ -48,8 +45,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
RecordCrudModule,
FeatureFlagModule,
FilesFieldModule,
- ObjectMetadataModule,
- FieldMetadataModule,
PermissionsModule,
ViewToolsModule,
WorkspaceCacheModule,
@@ -59,7 +54,7 @@ import { ToolRegistryService } from './services/tool-registry.service';
RoleToolsModule,
AgentToolsModule,
UserRoleModule,
- ValidationRuleModule,
+ MetadataToolsModule,
EmailingModule,
TypeOrmModule.forFeature([UserEntity, FileEntity]),
],
@@ -72,7 +67,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
ActionToolProvider,
DashboardToolProvider,
DatabaseToolProvider,
- MetadataToolProvider,
LogicFunctionToolProvider,
WorkflowToolProvider,
{
@@ -80,14 +74,12 @@ import { ToolRegistryService } from './services/tool-registry.service';
useFactory: (
actionProvider: ActionToolProvider,
databaseProvider: DatabaseToolProvider,
- metadataProvider: MetadataToolProvider,
logicFunctionProvider: LogicFunctionToolProvider,
workflowProvider: WorkflowToolProvider,
dashboardProvider: DashboardToolProvider,
) => [
actionProvider,
databaseProvider,
- metadataProvider,
logicFunctionProvider,
workflowProvider,
dashboardProvider,
@@ -95,7 +87,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
inject: [
ActionToolProvider,
DatabaseToolProvider,
- MetadataToolProvider,
LogicFunctionToolProvider,
WorkflowToolProvider,
DashboardToolProvider,
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/field-metadata.module.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/field-metadata.module.ts
index a6080fc065f..08dcf7788e7 100644
--- a/packages/twenty-server/src/engine/metadata-modules/field-metadata/field-metadata.module.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/field-metadata.module.ts
@@ -10,7 +10,6 @@ import { DerivedFieldMetadataIdsModule } from 'src/engine/metadata-modules/deriv
import { FieldMetadataController } from 'src/engine/metadata-modules/field-metadata/controllers/field-metadata.controller';
import { FieldMetadataResolver } from 'src/engine/metadata-modules/field-metadata/field-metadata.resolver';
import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
-import { FieldMetadataToolsFactory } from 'src/engine/metadata-modules/field-metadata/tools/field-metadata-tools.factory';
import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
import { FlatFieldMetadataModule } from 'src/engine/metadata-modules/flat-field-metadata/flat-field-metadata.module';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
@@ -44,9 +43,8 @@ import { FieldMetadataEntity } from './field-metadata.entity';
providers: [
FieldMetadataService,
FieldMetadataResolver,
- FieldMetadataToolsFactory,
provideWorkspaceScopedRepository(FieldMetadataEntity),
],
- exports: [FieldMetadataService, FieldMetadataToolsFactory],
+ exports: [FieldMetadataService],
})
export class FieldMetadataModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/constants/relation-type-description.constant.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/constants/relation-type-description.constant.ts
new file mode 100644
index 00000000000..ebf7e709192
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/constants/relation-type-description.constant.ts
@@ -0,0 +1,4 @@
+export const RELATION_TYPE_DESCRIPTION =
+ 'Relation direction from the perspective of the object the field is created on. ' +
+ "MANY_TO_ONE: the field points to a single target record; this object owns the foreign key and gets a writable '<fieldName>Id' on its create/update inputs. Use it for 'belongs to one' fields. " +
+ "ONE_TO_MANY: the field is a read-only collection of target records; records are linked by writing the inverse '<fieldName>Id' on the target object.";
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/constants/select-options-description.constant.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/constants/select-options-description.constant.ts
new file mode 100644
index 00000000000..3fddef5086c
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/constants/select-options-description.constant.ts
@@ -0,0 +1,6 @@
+import {
+ DEFAULT_SELECT_OPTION_COLOR,
+ TAG_COLORS,
+} from 'twenty-shared/constants';
+
+export const SELECT_OPTIONS_DESCRIPTION = `SELECT/MULTI_SELECT options: [{ label, value, position, color }]. color is one of ${TAG_COLORS.join(', ')}; defaults to ${DEFAULT_SELECT_OPTION_COLOR} when omitted.`;
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-field-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-field-metadata.tool.ts
new file mode 100644
index 00000000000..2be594fbc18
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-field-metadata.tool.ts
@@ -0,0 +1,65 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import {
+ FIELD_TYPE_DEFAULT_ICONS,
+ PermissionFlagType,
+} from 'twenty-shared/constants';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+import { createFieldMetadataInputSchema } from 'src/engine/metadata-modules/field-metadata/tools/schemas/create-field-metadata-input.schema';
+import { normalizeRelationCreationPayloadIcon } from 'src/engine/metadata-modules/field-metadata/tools/utils/normalize-relation-creation-payload-icon.util';
+
+@DefineTool({
+ name: 'create_field_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Create a new field on an object.',
+})
+export class CreateFieldMetadataTool extends BaseTool<
+ typeof createFieldMetadataInputSchema
+> {
+ readonly inputSchema = createFieldMetadataInputSchema;
+
+ constructor(private readonly fieldMetadataService: FieldMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof createFieldMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const { icon, relationCreationPayload, ...createFieldInput } = input;
+
+ const flatFieldMetadata = await this.fieldMetadataService.createOneField({
+ createFieldInput: {
+ ...createFieldInput,
+ icon: normalizeIconName(icon) ?? FIELD_TYPE_DEFAULT_ICONS[input.type],
+ relationCreationPayload: normalizeRelationCreationPayloadIcon(
+ relationCreationPayload,
+ ),
+ } as Parameters<
+ typeof this.fieldMetadataService.createOneField
+ >[0]['createFieldInput'],
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Created the field "${flatFieldMetadata.name}".`,
+ result: {
+ id: flatFieldMetadata.id,
+ name: flatFieldMetadata.name,
+ label: flatFieldMetadata.label,
+ type: flatFieldMetadata.type,
+ objectMetadataId: flatFieldMetadata.objectMetadataId,
+ },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-many-field-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-many-field-metadata.tool.ts
new file mode 100644
index 00000000000..4dad8c7ee40
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-many-field-metadata.tool.ts
@@ -0,0 +1,70 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import {
+ FIELD_TYPE_DEFAULT_ICONS,
+ PermissionFlagType,
+} from 'twenty-shared/constants';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+import { createFieldMetadataInputSchema } from 'src/engine/metadata-modules/field-metadata/tools/schemas/create-field-metadata-input.schema';
+import { normalizeRelationCreationPayloadIcon } from 'src/engine/metadata-modules/field-metadata/tools/utils/normalize-relation-creation-payload-icon.util';
+
+const createManyFieldMetadataInputSchema = z.object({
+ fields: z
+ .array(createFieldMetadataInputSchema)
+ .min(1)
+ .max(20)
+ .describe('Fields to create (max 20).'),
+});
+
+@DefineTool({
+ name: 'create_many_field_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description:
+ 'Create multiple field metadata at once on one or more objects. More efficient than calling create_field_metadata multiple times. Each item follows the same schema as create_field_metadata.',
+})
+export class CreateManyFieldMetadataTool extends BaseTool<
+ typeof createManyFieldMetadataInputSchema
+> {
+ readonly inputSchema = createManyFieldMetadataInputSchema;
+
+ constructor(private readonly fieldMetadataService: FieldMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof createManyFieldMetadataInputSchema
+ >): Promise<ToolOutput> {
+ await this.fieldMetadataService.createManyFields({
+ createFieldInputs: input.fields.map(
+ ({ icon, relationCreationPayload, ...createFieldInput }) => ({
+ ...createFieldInput,
+ icon:
+ normalizeIconName(icon) ??
+ FIELD_TYPE_DEFAULT_ICONS[createFieldInput.type],
+ relationCreationPayload: normalizeRelationCreationPayloadIcon(
+ relationCreationPayload,
+ ),
+ }),
+ ) as Parameters<
+ typeof this.fieldMetadataService.createManyFields
+ >[0]['createFieldInputs'],
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Created ${input.fields.length} field(s).`,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-many-relation-fields.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-many-relation-fields.tool.ts
new file mode 100644
index 00000000000..5702cc6dfaf
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/create-many-relation-fields.tool.ts
@@ -0,0 +1,95 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import {
+ FIELD_TYPE_DEFAULT_ICONS,
+ PermissionFlagType,
+} from 'twenty-shared/constants';
+import { FieldMetadataType, RelationType } from 'twenty-shared/types';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+import { RELATION_TYPE_DESCRIPTION } from 'src/engine/metadata-modules/field-metadata/tools/constants/relation-type-description.constant';
+
+const createManyRelationFieldsInputSchema = z.object({
+ relations: z
+ .array(
+ z.object({
+ objectMetadataId: z.string().uuid().describe('Source object ID'),
+ name: z.string().describe('Field name (camelCase)'),
+ label: z.string().describe('Display label'),
+ description: z.string().optional().describe('Description'),
+ icon: z
+ .string()
+ .optional()
+ .describe('Tabler icon name for the relation field (e.g. IconUsers)'),
+ type: z.nativeEnum(RelationType).describe(RELATION_TYPE_DESCRIPTION),
+ targetObjectMetadataId: z.string().uuid().describe('Target object ID'),
+ targetFieldLabel: z.string().describe('Inverse field label'),
+ targetFieldIcon: z
+ .string()
+ .describe(
+ 'Inverse field Tabler icon name (e.g. IconBuildingSkyscraper)',
+ ),
+ }),
+ )
+ .min(1)
+ .max(20)
+ .describe('Relations to create (max 20).'),
+});
+
+@DefineTool({
+ name: 'create_many_relation_fields',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Create multiple relation fields between objects at once.',
+})
+export class CreateManyRelationFieldsTool extends BaseTool<
+ typeof createManyRelationFieldsInputSchema
+> {
+ readonly inputSchema = createManyRelationFieldsInputSchema;
+
+ constructor(private readonly fieldMetadataService: FieldMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof createManyRelationFieldsInputSchema
+ >): Promise<ToolOutput> {
+ await this.fieldMetadataService.createManyFields({
+ createFieldInputs: input.relations.map((relation) => ({
+ objectMetadataId: relation.objectMetadataId,
+ type: FieldMetadataType.RELATION,
+ name: relation.name,
+ label: relation.label,
+ description: relation.description,
+ icon:
+ normalizeIconName(relation.icon) ??
+ FIELD_TYPE_DEFAULT_ICONS[FieldMetadataType.RELATION],
+ relationCreationPayload: {
+ type: relation.type,
+ targetObjectMetadataId: relation.targetObjectMetadataId,
+ targetFieldLabel: relation.targetFieldLabel,
+ targetFieldIcon:
+ normalizeIconName(relation.targetFieldIcon) ??
+ FIELD_TYPE_DEFAULT_ICONS[FieldMetadataType.RELATION],
+ },
+ })) as Parameters<
+ typeof this.fieldMetadataService.createManyFields
+ >[0]['createFieldInputs'],
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Created ${input.relations.length} relation field(s).`,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/delete-field-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/delete-field-metadata.tool.ts
new file mode 100644
index 00000000000..9ff60d47221
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/delete-field-metadata.tool.ts
@@ -0,0 +1,48 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+
+const deleteFieldMetadataInputSchema = z.object({
+ id: z.string().uuid().describe('Field ID'),
+});
+
+@DefineTool({
+ name: 'delete_field_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Delete a field by ID.',
+})
+export class DeleteFieldMetadataTool extends BaseTool<
+ typeof deleteFieldMetadataInputSchema
+> {
+ readonly inputSchema = deleteFieldMetadataInputSchema;
+
+ constructor(private readonly fieldMetadataService: FieldMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof deleteFieldMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const flatFieldMetadata = await this.fieldMetadataService.deleteOneField({
+ deleteOneFieldInput: { id: input.id },
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Deleted the field "${flatFieldMetadata.name}".`,
+ result: { id: flatFieldMetadata.id, deleted: true },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/field-metadata-tools.factory.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/field-metadata-tools.factory.ts
deleted file mode 100644
index 8ec992c06cc..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/field-metadata-tools.factory.ts
+++ /dev/null
@@ -1,526 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-import {
- DEFAULT_SELECT_OPTION_COLOR,
- FIELD_TYPE_DEFAULT_ICONS,
- TAG_COLORS,
-} from 'twenty-shared/constants';
-import { FieldMetadataType, RelationType } from 'twenty-shared/types';
-import { z } from 'zod';
-
-import {
- ObjectMetadataException,
- ObjectMetadataExceptionCode,
-} from 'src/engine/metadata-modules/object-metadata/object-metadata.exception';
-import { METADATA_TOOL_EXCLUDED_FIELD_NAMES } from 'src/engine/core-modules/tool-provider/constants/metadata-tool-excluded-field-names.constant';
-import { compactMetadataOutput } from 'src/engine/core-modules/tool-provider/utils/compact-metadata-output.util';
-import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
-import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
-import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
-import { getObjectMetadataIdByName } from 'src/engine/metadata-modules/flat-object-metadata/utils/get-object-metadata-id-by-name.util';
-import { isDefined } from 'twenty-shared/utils';
-
-const FIELD_STRIP_WHEN_NULLISH = [
- 'options',
- 'settings',
- 'defaultValue',
- 'description',
- 'icon',
- 'deletedAt',
-];
-
-const FIELD_STRIP_WHEN_FALSE = ['isLabelSyncedWithName'];
-
-// isUIEditable defaults to true, so only the non-default false value is informative
-const FIELD_STRIP_WHEN_TRUE = ['isUIEditable'];
-
-const RELATION_TYPE_DESCRIPTION =
- 'Relation direction from the perspective of the object the field is created on. ' +
- "MANY_TO_ONE: the field points to a single target record; this object owns the foreign key and gets a writable '<fieldName>Id' on its create/update inputs. Use it for 'belongs to one' fields. " +
- "ONE_TO_MANY: the field is a read-only collection of target records; records are linked by writing the inverse '<fieldName>Id' on the target object.";
-
-const SELECT_OPTIONS_DESCRIPTION = `SELECT/MULTI_SELECT options: [{ label, value, position, color }]. color is one of ${TAG_COLORS.join(', ')}; defaults to ${DEFAULT_SELECT_OPTION_COLOR} when omitted.`;
-
-const RelationCreationPayloadSchema = z.object({
- type: z.nativeEnum(RelationType).describe(RELATION_TYPE_DESCRIPTION),
- targetObjectMetadataId: z.string().uuid().describe('Target object ID'),
- targetFieldLabel: z
- .string()
- .describe(
- 'Display label of the inverse relation field created on the target object',
- ),
- targetFieldIcon: z
- .string()
- .optional()
- .describe(
- 'Tabler icon name for the inverse field (e.g. IconBuildingSkyscraper). Falls back to the relation default.',
- ),
-});
-
-const GetFieldMetadataInputSchema = z.object({
- id: z.uuid().optional().describe('Field ID. Returns one field if set.'),
- objectMetadataId: z.uuid().optional().describe('Filter by object ID.'),
- objectName: z
- .string()
- .optional()
- .describe(
- 'Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Convenient alternative to objectMetadataId so you do not need to resolve the object id first.',
- ),
- includeFullSystemFields: z
- .boolean()
- .default(false)
- .describe(
- "Keep false (default) for listing or inspecting fields — system fields then return as compact {id, name, type}, which is enough to know which fields exist and their types. Only set true when you specifically need a system field's full configuration (settings, defaultValue, relation targets).",
- ),
- limit: z
- .number()
- .int()
- .min(1)
- .max(100)
- .default(100)
- .describe('Max fields to return.'),
-});
-
-const CreateFieldMetadataInputSchema = z.object({
- objectMetadataId: z.string().uuid().describe('Target object ID'),
- type: z.nativeEnum(FieldMetadataType).describe('Field type'),
- name: z.string().describe('Field name (camelCase)'),
- label: z.string().describe('Display label'),
- description: z.string().optional().describe('Description'),
- icon: z
- .string()
- .optional()
- .describe(
- 'Tabler icon name, PascalCase with "Icon" prefix (e.g. IconCurrencyDollar, IconCalendarTime, IconPaw). Set one matching the field meaning; falls back to a type-based default.',
- ),
- isNullable: z.boolean().optional().describe('Nullable'),
- isUnique: z.boolean().optional().describe('Unique constraint'),
- defaultValue: z.unknown().optional().describe('Default value'),
- options: z.unknown().optional().describe(SELECT_OPTIONS_DESCRIPTION),
- settings: z.unknown().optional().describe('Field settings'),
- isLabelSyncedWithName: z
- .boolean()
- .optional()
- .describe('Sync label with name'),
- isRemoteCreation: z.boolean().optional().describe('Remote field creation'),
- relationCreationPayload: RelationCreationPayloadSchema.optional().describe(
- 'Required when type is RELATION. Defines the relation direction and the inverse field created on the target object.',
- ),
-});
-
-const UpdateFieldMetadataInputSchema = z.object({
- id: z.string().uuid().describe('Field ID'),
- name: z.string().optional().describe('Field name'),
- label: z.string().optional().describe('Display label'),
- description: z.string().optional().describe('Description'),
- icon: z
- .string()
- .optional()
- .describe('Tabler icon name (e.g. IconCurrencyDollar)'),
- isActive: z.boolean().optional().describe('Active state'),
- isNullable: z.boolean().optional().describe('Nullable'),
- isUnique: z.boolean().optional().describe('Unique constraint'),
- defaultValue: z.unknown().optional().describe('Default value'),
- options: z.unknown().optional().describe(SELECT_OPTIONS_DESCRIPTION),
- settings: z.unknown().optional().describe('Field settings'),
- isLabelSyncedWithName: z
- .boolean()
- .optional()
- .describe('Sync label with name'),
-});
-
-const DeleteFieldMetadataInputSchema = z.object({
- id: z.string().uuid().describe('Field ID'),
-});
-
-const CreateManyFieldMetadataInputSchema = z.object({
- fields: z
- .array(CreateFieldMetadataInputSchema)
- .min(1)
- .max(20)
- .describe('Fields to create (max 20).'),
-});
-
-const UpdateManyFieldMetadataInputSchema = z.object({
- fields: z
- .array(UpdateFieldMetadataInputSchema)
- .min(1)
- .max(20)
- .describe('Fields to update (max 20).'),
-});
-
-const CreateManyRelationFieldsInputSchema = z.object({
- relations: z
- .array(
- z.object({
- objectMetadataId: z.string().uuid().describe('Source object ID'),
- name: z.string().describe('Field name (camelCase)'),
- label: z.string().describe('Display label'),
- description: z.string().optional().describe('Description'),
- icon: z
- .string()
- .optional()
- .describe('Tabler icon name for the relation field (e.g. IconUsers)'),
- type: z.nativeEnum(RelationType).describe(RELATION_TYPE_DESCRIPTION),
- targetObjectMetadataId: z.string().uuid().describe('Target object ID'),
- targetFieldLabel: z.string().describe('Inverse field label'),
- targetFieldIcon: z
- .string()
- .describe(
- 'Inverse field Tabler icon name (e.g. IconBuildingSkyscraper)',
- ),
- }),
- )
- .min(1)
- .max(20)
- .describe('Relations to create (max 20).'),
-});
-
-const normalizeRelationCreationPayloadIcon = (
- relationCreationPayload: unknown,
-): unknown => {
- if (
- !isDefined(relationCreationPayload) ||
- typeof relationCreationPayload !== 'object' ||
- Array.isArray(relationCreationPayload)
- ) {
- return relationCreationPayload;
- }
-
- const { targetFieldIcon } = relationCreationPayload as {
- targetFieldIcon?: string;
- };
-
- return {
- ...relationCreationPayload,
- targetFieldIcon:
- normalizeIconName(targetFieldIcon) ??
- FIELD_TYPE_DEFAULT_ICONS[FieldMetadataType.RELATION],
- };
-};
-
-@Injectable()
-export class FieldMetadataToolsFactory {
- constructor(
- private readonly fieldMetadataService: FieldMetadataService,
- private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
- ) {}
-
- private async getObjectMetadataIdOrThrow(
- workspaceId: string,
- objectName: string,
- ): Promise<string> {
- const { flatObjectMetadataMaps } =
- await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
- {
- workspaceId,
- flatMapsKeys: ['flatObjectMetadataMaps'],
- },
- );
-
- const objectMetadataId = getObjectMetadataIdByName({
- flatObjectMetadataMaps,
- objectName,
- });
-
- if (!isDefined(objectMetadataId)) {
- throw new ObjectMetadataException(
- `Object "${objectName}" not found. Use get_object_metadata to list available objects.`,
- ObjectMetadataExceptionCode.OBJECT_METADATA_NOT_FOUND,
- );
- }
-
- return objectMetadataId;
- }
-
- generateTools(workspaceId: string): ToolSet {
- return {
- get_field_metadata: {
- description:
- "Returns an array of fields. System fields are returned as compact {id, name, type} — enough to know which fields exist and their types. Keep includeFullSystemFields at its default (false); only set it true when you specifically need a system field's full configuration (settings, defaultValue, relation targets). Internal fields (searchVector, position, updatedBy) are excluded.",
- inputSchema: GetFieldMetadataInputSchema,
- execute: async (parameters: {
- id?: string;
- objectMetadataId?: string;
- objectName?: string;
- includeFullSystemFields?: boolean;
- limit?: number;
- }) => {
- const objectMetadataId =
- parameters.objectMetadataId ??
- (parameters.objectName
- ? await this.getObjectMetadataIdOrThrow(
- workspaceId,
- parameters.objectName,
- )
- : undefined);
-
- const rawResults =
- await this.fieldMetadataService.findManyWithinWorkspace({
- workspaceId,
- fieldMetadataId: parameters.id,
- objectMetadataId,
- limit: parameters.limit ?? 100,
- });
-
- const compactedFields = (
- rawResults as unknown as Record<string, unknown>[]
- )
- .filter(
- (field) =>
- !METADATA_TOOL_EXCLUDED_FIELD_NAMES.has(field.name as string),
- )
- .map((field) => {
- if (field.isSystem && !parameters.includeFullSystemFields) {
- return {
- id: field.id,
- name: field.name,
- type: field.type,
- };
- }
-
- return compactMetadataOutput(
- { ...field },
- {
- stripWhenNullish: FIELD_STRIP_WHEN_NULLISH,
- stripWhenFalse: FIELD_STRIP_WHEN_FALSE,
- stripWhenTrue: FIELD_STRIP_WHEN_TRUE,
- },
- );
- });
-
- return compactedFields;
- },
- },
- create_field_metadata: {
- description: 'Create a new field on an object.',
- inputSchema: CreateFieldMetadataInputSchema,
- execute: async (parameters: {
- objectMetadataId: string;
- type: FieldMetadataType;
- name: string;
- label: string;
- description?: string;
- icon?: string;
- isNullable?: boolean;
- isUnique?: boolean;
- defaultValue?: unknown;
- options?: unknown;
- settings?: unknown;
- isLabelSyncedWithName?: boolean;
- isRemoteCreation?: boolean;
- relationCreationPayload?: unknown;
- }) => {
- const { icon, relationCreationPayload, ...createFieldInput } =
- parameters;
-
- const flatFieldMetadata =
- await this.fieldMetadataService.createOneField({
- createFieldInput: {
- ...createFieldInput,
- icon:
- normalizeIconName(icon) ??
- FIELD_TYPE_DEFAULT_ICONS[parameters.type],
- relationCreationPayload: normalizeRelationCreationPayloadIcon(
- relationCreationPayload,
- ),
- } as Parameters<
- typeof this.fieldMetadataService.createOneField
- >[0]['createFieldInput'],
- workspaceId,
- });
-
- return {
- id: flatFieldMetadata.id,
- name: flatFieldMetadata.name,
- label: flatFieldMetadata.label,
- type: flatFieldMetadata.type,
- objectMetadataId: flatFieldMetadata.objectMetadataId,
- };
- },
- },
- update_field_metadata: {
- description:
- 'Update a field. Provide field ID and properties to change.',
- inputSchema: UpdateFieldMetadataInputSchema,
- execute: async (parameters: {
- id: string;
- name?: string;
- label?: string;
- description?: string;
- icon?: string;
- isActive?: boolean;
- isNullable?: boolean;
- isUnique?: boolean;
- defaultValue?: unknown;
- options?: unknown;
- settings?: unknown;
- isLabelSyncedWithName?: boolean;
- }) => {
- const { id, icon, ...update } = parameters;
- const normalizedIcon = normalizeIconName(icon);
-
- const flatFieldMetadata =
- await this.fieldMetadataService.updateOneField({
- updateFieldInput: {
- id,
- ...update,
- ...(isDefined(normalizedIcon) ? { icon: normalizedIcon } : {}),
- } as Parameters<
- typeof this.fieldMetadataService.updateOneField
- >[0]['updateFieldInput'],
- workspaceId,
- });
-
- return {
- id: flatFieldMetadata.id,
- name: flatFieldMetadata.name,
- label: flatFieldMetadata.label,
- type: flatFieldMetadata.type,
- };
- },
- },
- delete_field_metadata: {
- description: 'Delete a field by ID.',
- inputSchema: DeleteFieldMetadataInputSchema,
- execute: async (parameters: { id: string }) => {
- const flatFieldMetadata =
- await this.fieldMetadataService.deleteOneField({
- deleteOneFieldInput: { id: parameters.id },
- workspaceId,
- });
-
- return { id: flatFieldMetadata.id, success: true };
- },
- },
- create_many_field_metadata: {
- description:
- 'Create multiple field metadata at once on one or more objects. More efficient than calling create_field_metadata multiple times. Each item follows the same schema as create_field_metadata.',
- inputSchema: CreateManyFieldMetadataInputSchema,
- execute: async (parameters: {
- fields: Array<{
- objectMetadataId: string;
- type: FieldMetadataType;
- name: string;
- label: string;
- description?: string;
- icon?: string;
- isNullable?: boolean;
- isUnique?: boolean;
- defaultValue?: unknown;
- options?: unknown;
- settings?: unknown;
- isLabelSyncedWithName?: boolean;
- isRemoteCreation?: boolean;
- relationCreationPayload?: unknown;
- }>;
- }) => {
- await this.fieldMetadataService.createManyFields({
- createFieldInputs: parameters.fields.map(
- ({ icon, relationCreationPayload, ...createFieldInput }) => ({
- ...createFieldInput,
- icon:
- normalizeIconName(icon) ??
- FIELD_TYPE_DEFAULT_ICONS[createFieldInput.type],
- relationCreationPayload: normalizeRelationCreationPayloadIcon(
- relationCreationPayload,
- ),
- }),
- ) as Parameters<
- typeof this.fieldMetadataService.createManyFields
- >[0]['createFieldInputs'],
- workspaceId,
- });
-
- return true;
- },
- },
- update_many_field_metadata: {
- description:
- 'Update multiple field metadata at once. More efficient than calling update_field_metadata multiple times. Each item must include the field ID and the properties to update.',
- inputSchema: UpdateManyFieldMetadataInputSchema,
- execute: async (parameters: {
- fields: Array<{
- id: string;
- name?: string;
- label?: string;
- description?: string;
- icon?: string;
- isActive?: boolean;
- isNullable?: boolean;
- isUnique?: boolean;
- defaultValue?: unknown;
- options?: unknown;
- settings?: unknown;
- isLabelSyncedWithName?: boolean;
- }>;
- }) => {
- await Promise.all(
- parameters.fields.map(async ({ id, icon, ...update }) => {
- const normalizedIcon = normalizeIconName(icon);
-
- await this.fieldMetadataService.updateOneField({
- updateFieldInput: {
- id,
- ...update,
- ...(isDefined(normalizedIcon)
- ? { icon: normalizedIcon }
- : {}),
- } as Parameters<
- typeof this.fieldMetadataService.updateOneField
- >[0]['updateFieldInput'],
- workspaceId,
- });
- }),
- );
-
- return true;
- },
- },
- create_many_relation_fields: {
- description: 'Create multiple relation fields between objects at once.',
- inputSchema: CreateManyRelationFieldsInputSchema,
- execute: async (parameters: {
- relations: Array<{
- objectMetadataId: string;
- name: string;
- label: string;
- description?: string;
- icon?: string;
- type: RelationType;
- targetObjectMetadataId: string;
- targetFieldLabel: string;
- targetFieldIcon: string;
- }>;
- }) => {
- await this.fieldMetadataService.createManyFields({
- createFieldInputs: parameters.relations.map((relation) => ({
- objectMetadataId: relation.objectMetadataId,
- type: FieldMetadataType.RELATION,
- name: relation.name,
- label: relation.label,
- description: relation.description,
- icon:
- normalizeIconName(relation.icon) ??
- FIELD_TYPE_DEFAULT_ICONS[FieldMetadataType.RELATION],
- relationCreationPayload: {
- type: relation.type,
- targetObjectMetadataId: relation.targetObjectMetadataId,
- targetFieldLabel: relation.targetFieldLabel,
- targetFieldIcon:
- normalizeIconName(relation.targetFieldIcon) ??
- FIELD_TYPE_DEFAULT_ICONS[FieldMetadataType.RELATION],
- },
- })) as Parameters<
- typeof this.fieldMetadataService.createManyFields
- >[0]['createFieldInputs'],
- workspaceId,
- });
-
- return true;
- },
- },
- };
- }
-}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/get-field-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/get-field-metadata.tool.ts
new file mode 100644
index 00000000000..bdcad67385c
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/get-field-metadata.tool.ts
@@ -0,0 +1,122 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { z } from 'zod';
+
+import { METADATA_TOOL_EXCLUDED_FIELD_NAMES } from 'src/engine/core-modules/tool-provider/constants/metadata-tool-excluded-field-names.constant';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { compactMetadataOutput } from 'src/engine/core-modules/tool-provider/utils/compact-metadata-output.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+import { MetadataToolIdentifierService } from 'src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service';
+
+const FIELD_STRIP_WHEN_NULLISH = [
+ 'options',
+ 'settings',
+ 'defaultValue',
+ 'description',
+ 'icon',
+ 'deletedAt',
+];
+
+const FIELD_STRIP_WHEN_FALSE = ['isLabelSyncedWithName'];
+
+// isUIEditable defaults to true, so only the non-default false value is informative
+const FIELD_STRIP_WHEN_TRUE = ['isUIEditable'];
+
+const getFieldMetadataInputSchema = z.object({
+ id: z.uuid().optional().describe('Field ID. Returns one field if set.'),
+ objectMetadataId: z.uuid().optional().describe('Filter by object ID.'),
+ objectName: z
+ .string()
+ .optional()
+ .describe(
+ 'Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Convenient alternative to objectMetadataId so you do not need to resolve the object id first.',
+ ),
+ includeFullSystemFields: z
+ .boolean()
+ .default(false)
+ .describe(
+ "Keep false (default) for listing or inspecting fields — system fields then return as compact {id, name, type}, which is enough to know which fields exist and their types. Only set true when you specifically need a system field's full configuration (settings, defaultValue, relation targets).",
+ ),
+ limit: z
+ .number()
+ .int()
+ .min(1)
+ .max(100)
+ .default(100)
+ .describe('Max fields to return.'),
+});
+
+@DefineTool({
+ name: 'get_field_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description:
+ "Returns { fields: [...] } in the result. System fields are returned as compact {id, name, type} — enough to know which fields exist and their types. Keep includeFullSystemFields at its default (false); only set it true when you specifically need a system field's full configuration (settings, defaultValue, relation targets). Internal fields (searchVector, position, updatedBy) are excluded.",
+})
+export class GetFieldMetadataTool extends BaseTool<
+ typeof getFieldMetadataInputSchema
+> {
+ readonly inputSchema = getFieldMetadataInputSchema;
+
+ constructor(
+ private readonly fieldMetadataService: FieldMetadataService,
+ private readonly metadataToolIdentifierService: MetadataToolIdentifierService,
+ ) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<typeof getFieldMetadataInputSchema>): Promise<ToolOutput> {
+ const objectMetadataId =
+ input.objectMetadataId ??
+ (input.objectName
+ ? await this.metadataToolIdentifierService.getObjectMetadataIdOrThrow({
+ workspaceId,
+ objectName: input.objectName,
+ })
+ : undefined);
+
+ const rawResults = await this.fieldMetadataService.findManyWithinWorkspace({
+ workspaceId,
+ fieldMetadataId: input.id,
+ objectMetadataId,
+ limit: input.limit ?? 100,
+ });
+
+ const compactedFields = (rawResults as unknown as Record<string, unknown>[])
+ .filter(
+ (field) =>
+ !METADATA_TOOL_EXCLUDED_FIELD_NAMES.has(field.name as string),
+ )
+ .map((field) => {
+ if (field.isSystem && !input.includeFullSystemFields) {
+ return {
+ id: field.id,
+ name: field.name,
+ type: field.type,
+ };
+ }
+
+ return compactMetadataOutput(
+ { ...field },
+ {
+ stripWhenNullish: FIELD_STRIP_WHEN_NULLISH,
+ stripWhenFalse: FIELD_STRIP_WHEN_FALSE,
+ stripWhenTrue: FIELD_STRIP_WHEN_TRUE,
+ },
+ );
+ });
+
+ return {
+ success: true,
+ message: `Found ${compactedFields.length} field(s).`,
+ result: { fields: compactedFields },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/schemas/create-field-metadata-input.schema.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/schemas/create-field-metadata-input.schema.ts
new file mode 100644
index 00000000000..6389c477c44
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/schemas/create-field-metadata-input.schema.ts
@@ -0,0 +1,50 @@
+import { FieldMetadataType, RelationType } from 'twenty-shared/types';
+import { z } from 'zod';
+
+import { RELATION_TYPE_DESCRIPTION } from 'src/engine/metadata-modules/field-metadata/tools/constants/relation-type-description.constant';
+import { SELECT_OPTIONS_DESCRIPTION } from 'src/engine/metadata-modules/field-metadata/tools/constants/select-options-description.constant';
+
+const relationCreationPayloadSchema = z.object({
+ type: z.nativeEnum(RelationType).describe(RELATION_TYPE_DESCRIPTION),
+ targetObjectMetadataId: z.string().uuid().describe('Target object ID'),
+ targetFieldLabel: z
+ .string()
+ .describe(
+ 'Display label of the inverse relation field created on the target object',
+ ),
+ targetFieldIcon: z
+ .string()
+ .optional()
+ .describe(
+ 'Tabler icon name for the inverse field (e.g. IconBuildingSkyscraper). Falls back to the relation default.',
+ ),
+});
+
+export const createFieldMetadataInputSchema = z.object({
+ objectMetadataId: z.string().uuid().describe('Target object ID'),
+ type: z.nativeEnum(FieldMetadataType).describe('Field type'),
+ name: z.string().describe('Field name (camelCase)'),
+ label: z.string().describe('Display label'),
+ description: z.string().optional().describe('Description'),
+ icon: z
+ .string()
+ .optional()
+ .describe(
+ 'Tabler icon name, PascalCase with "Icon" prefix (e.g. IconCurrencyDollar, IconCalendarTime, IconPaw). Set one matching the field meaning; falls back to a type-based default.',
+ ),
+ isNullable: z.boolean().optional().describe('Nullable'),
+ isUnique: z.boolean().optional().describe('Unique constraint'),
+ defaultValue: z.unknown().optional().describe('Default value'),
+ options: z.unknown().optional().describe(SELECT_OPTIONS_DESCRIPTION),
+ settings: z.unknown().optional().describe('Field settings'),
+ isLabelSyncedWithName: z
+ .boolean()
+ .optional()
+ .describe('Sync label with name'),
+ isRemoteCreation: z.boolean().optional().describe('Remote field creation'),
+ relationCreationPayload: relationCreationPayloadSchema
+ .optional()
+ .describe(
+ 'Required when type is RELATION. Defines the relation direction and the inverse field created on the target object.',
+ ),
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/schemas/update-field-metadata-input.schema.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/schemas/update-field-metadata-input.schema.ts
new file mode 100644
index 00000000000..cc5a78b3148
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/schemas/update-field-metadata-input.schema.ts
@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+import { SELECT_OPTIONS_DESCRIPTION } from 'src/engine/metadata-modules/field-metadata/tools/constants/select-options-description.constant';
+
+export const updateFieldMetadataInputSchema = z.object({
+ id: z.string().uuid().describe('Field ID'),
+ name: z.string().optional().describe('Field name'),
+ label: z.string().optional().describe('Display label'),
+ description: z.string().optional().describe('Description'),
+ icon: z
+ .string()
+ .optional()
+ .describe('Tabler icon name (e.g. IconCurrencyDollar)'),
+ isActive: z.boolean().optional().describe('Active state'),
+ isNullable: z.boolean().optional().describe('Nullable'),
+ isUnique: z.boolean().optional().describe('Unique constraint'),
+ defaultValue: z.unknown().optional().describe('Default value'),
+ options: z.unknown().optional().describe(SELECT_OPTIONS_DESCRIPTION),
+ settings: z.unknown().optional().describe('Field settings'),
+ isLabelSyncedWithName: z
+ .boolean()
+ .optional()
+ .describe('Sync label with name'),
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/update-field-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/update-field-metadata.tool.ts
new file mode 100644
index 00000000000..1b13305e222
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/update-field-metadata.tool.ts
@@ -0,0 +1,60 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { isDefined } from 'twenty-shared/utils';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+import { updateFieldMetadataInputSchema } from 'src/engine/metadata-modules/field-metadata/tools/schemas/update-field-metadata-input.schema';
+
+@DefineTool({
+ name: 'update_field_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Update a field. Provide field ID and properties to change.',
+})
+export class UpdateFieldMetadataTool extends BaseTool<
+ typeof updateFieldMetadataInputSchema
+> {
+ readonly inputSchema = updateFieldMetadataInputSchema;
+
+ constructor(private readonly fieldMetadataService: FieldMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof updateFieldMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const { id, icon, ...update } = input;
+ const normalizedIcon = normalizeIconName(icon);
+
+ const flatFieldMetadata = await this.fieldMetadataService.updateOneField({
+ updateFieldInput: {
+ id,
+ ...update,
+ ...(isDefined(normalizedIcon) ? { icon: normalizedIcon } : {}),
+ } as Parameters<
+ typeof this.fieldMetadataService.updateOneField
+ >[0]['updateFieldInput'],
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Updated the field "${flatFieldMetadata.name}".`,
+ result: {
+ id: flatFieldMetadata.id,
+ name: flatFieldMetadata.name,
+ label: flatFieldMetadata.label,
+ type: flatFieldMetadata.type,
+ },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/update-many-field-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/update-many-field-metadata.tool.ts
new file mode 100644
index 00000000000..3185c26e63c
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/update-many-field-metadata.tool.ts
@@ -0,0 +1,67 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { isDefined } from 'twenty-shared/utils';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { FieldMetadataService } from 'src/engine/metadata-modules/field-metadata/services/field-metadata.service';
+import { updateFieldMetadataInputSchema } from 'src/engine/metadata-modules/field-metadata/tools/schemas/update-field-metadata-input.schema';
+
+const updateManyFieldMetadataInputSchema = z.object({
+ fields: z
+ .array(updateFieldMetadataInputSchema)
+ .min(1)
+ .max(20)
+ .describe('Fields to update (max 20).'),
+});
+
+@DefineTool({
+ name: 'update_many_field_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description:
+ 'Update multiple field metadata at once. More efficient than calling update_field_metadata multiple times. Each item must include the field ID and the properties to update.',
+})
+export class UpdateManyFieldMetadataTool extends BaseTool<
+ typeof updateManyFieldMetadataInputSchema
+> {
+ readonly inputSchema = updateManyFieldMetadataInputSchema;
+
+ constructor(private readonly fieldMetadataService: FieldMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof updateManyFieldMetadataInputSchema
+ >): Promise<ToolOutput> {
+ await Promise.all(
+ input.fields.map(async ({ id, icon, ...update }) => {
+ const normalizedIcon = normalizeIconName(icon);
+
+ await this.fieldMetadataService.updateOneField({
+ updateFieldInput: {
+ id,
+ ...update,
+ ...(isDefined(normalizedIcon) ? { icon: normalizedIcon } : {}),
+ } as Parameters<
+ typeof this.fieldMetadataService.updateOneField
+ >[0]['updateFieldInput'],
+ workspaceId,
+ });
+ }),
+ );
+
+ return {
+ success: true,
+ message: `Updated ${input.fields.length} field(s).`,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/utils/normalize-relation-creation-payload-icon.util.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/utils/normalize-relation-creation-payload-icon.util.ts
new file mode 100644
index 00000000000..1a088b2ae99
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/tools/utils/normalize-relation-creation-payload-icon.util.ts
@@ -0,0 +1,28 @@
+import { FIELD_TYPE_DEFAULT_ICONS } from 'twenty-shared/constants';
+import { FieldMetadataType } from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
+
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+
+export const normalizeRelationCreationPayloadIcon = (
+ relationCreationPayload: unknown,
+): unknown => {
+ if (
+ !isDefined(relationCreationPayload) ||
+ typeof relationCreationPayload !== 'object' ||
+ Array.isArray(relationCreationPayload)
+ ) {
+ return relationCreationPayload;
+ }
+
+ const { targetFieldIcon } = relationCreationPayload as {
+ targetFieldIcon?: string;
+ };
+
+ return {
+ ...relationCreationPayload,
+ targetFieldIcon:
+ normalizeIconName(targetFieldIcon) ??
+ FIELD_TYPE_DEFAULT_ICONS[FieldMetadataType.RELATION],
+ };
+};
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/object-metadata.module.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/object-metadata.module.ts
index a4d3e521034..58d340f7ab9 100644
--- a/packages/twenty-server/src/engine/metadata-modules/object-metadata/object-metadata.module.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/object-metadata.module.ts
@@ -16,7 +16,6 @@ import { ObjectMetadataEntity } from 'src/engine/metadata-modules/object-metadat
import { ObjectMetadataResolver } from 'src/engine/metadata-modules/object-metadata/object-metadata.resolver';
import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
import { ObjectRecordCountService } from 'src/engine/metadata-modules/object-metadata/object-record-count.service';
-import { ObjectMetadataToolsFactory } from 'src/engine/metadata-modules/object-metadata/tools/object-metadata-tools.factory';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
import { ViewModule } from 'src/engine/metadata-modules/view/view.module';
import { WorkspaceCacheStorageModule } from 'src/engine/workspace-cache-storage/workspace-cache-storage.module';
@@ -46,10 +45,9 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspac
ObjectMetadataResolver,
ObjectRecordCountService,
MostlyEmptyFieldsService,
- ObjectMetadataToolsFactory,
provideWorkspaceScopedRepository(ObjectMetadataEntity),
provideWorkspaceScopedRepository(FieldMetadataEntity),
],
- exports: [ObjectMetadataService, ObjectMetadataToolsFactory],
+ exports: [ObjectMetadataService],
})
export class ObjectMetadataModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/create-many-object-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/create-many-object-metadata.tool.ts
new file mode 100644
index 00000000000..9c3b3b81f07
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/create-many-object-metadata.tool.ts
@@ -0,0 +1,63 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
+import { createObjectMetadataInputSchema } from 'src/engine/metadata-modules/object-metadata/tools/schemas/create-object-metadata-input.schema';
+
+const createManyObjectMetadataInputSchema = z.object({
+ objects: z
+ .array(createObjectMetadataInputSchema)
+ .min(1)
+ .max(20)
+ .describe('Objects to create (max 20).'),
+});
+
+@DefineTool({
+ name: 'create_many_object_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description:
+ 'Create multiple objects at once. Batch version of create_object_metadata.',
+})
+export class CreateManyObjectMetadataTool extends BaseTool<
+ typeof createManyObjectMetadataInputSchema
+> {
+ readonly inputSchema = createManyObjectMetadataInputSchema;
+
+ constructor(private readonly objectMetadataService: ObjectMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof createManyObjectMetadataInputSchema
+ >): Promise<ToolOutput> {
+ await Promise.all(
+ input.objects.map(async ({ icon, ...createObjectInput }) => {
+ await this.objectMetadataService.createOneObject({
+ createObjectInput: {
+ ...createObjectInput,
+ icon: normalizeIconName(icon),
+ } as Parameters<
+ typeof this.objectMetadataService.createOneObject
+ >[0]['createObjectInput'],
+ workspaceId,
+ });
+ }),
+ );
+
+ return {
+ success: true,
+ message: `Created ${input.objects.length} object(s).`,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/create-object-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/create-object-metadata.tool.ts
new file mode 100644
index 00000000000..ee5f676226a
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/create-object-metadata.tool.ts
@@ -0,0 +1,58 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
+import { createObjectMetadataInputSchema } from 'src/engine/metadata-modules/object-metadata/tools/schemas/create-object-metadata-input.schema';
+
+@DefineTool({
+ name: 'create_object_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Create a new object in the workspace data model.',
+})
+export class CreateObjectMetadataTool extends BaseTool<
+ typeof createObjectMetadataInputSchema
+> {
+ readonly inputSchema = createObjectMetadataInputSchema;
+
+ constructor(private readonly objectMetadataService: ObjectMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof createObjectMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const { icon, ...createObjectInput } = input;
+
+ const flatObjectMetadata = await this.objectMetadataService.createOneObject(
+ {
+ createObjectInput: {
+ ...createObjectInput,
+ icon: normalizeIconName(icon),
+ } as Parameters<
+ typeof this.objectMetadataService.createOneObject
+ >[0]['createObjectInput'],
+ workspaceId,
+ },
+ );
+
+ return {
+ success: true,
+ message: `Created the object "${flatObjectMetadata.nameSingular}".`,
+ result: {
+ id: flatObjectMetadata.id,
+ nameSingular: flatObjectMetadata.nameSingular,
+ labelSingular: flatObjectMetadata.labelSingular,
+ },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/delete-object-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/delete-object-metadata.tool.ts
new file mode 100644
index 00000000000..276473556f1
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/delete-object-metadata.tool.ts
@@ -0,0 +1,50 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
+
+const deleteObjectMetadataInputSchema = z.object({
+ id: z.string().uuid().describe('Object ID'),
+});
+
+@DefineTool({
+ name: 'delete_object_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Delete an object by ID. Also deletes associated fields.',
+})
+export class DeleteObjectMetadataTool extends BaseTool<
+ typeof deleteObjectMetadataInputSchema
+> {
+ readonly inputSchema = deleteObjectMetadataInputSchema;
+
+ constructor(private readonly objectMetadataService: ObjectMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof deleteObjectMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const flatObjectMetadata = await this.objectMetadataService.deleteOneObject(
+ {
+ deleteObjectInput: { id: input.id },
+ workspaceId,
+ },
+ );
+
+ return {
+ success: true,
+ message: `Deleted the object "${flatObjectMetadata.nameSingular}".`,
+ result: { id: flatObjectMetadata.id, deleted: true },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/get-object-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/get-object-metadata.tool.ts
new file mode 100644
index 00000000000..8e155bba579
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/get-object-metadata.tool.ts
@@ -0,0 +1,175 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { type FieldMetadataType } from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
+import { z } from 'zod';
+
+import { METADATA_TOOL_EXCLUDED_FIELD_NAMES } from 'src/engine/core-modules/tool-provider/constants/metadata-tool-excluded-field-names.constant';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { compactMetadataOutput } from 'src/engine/core-modules/tool-provider/utils/compact-metadata-output.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
+import { fromFlatObjectMetadataToObjectMetadataDto } from 'src/engine/metadata-modules/flat-object-metadata/utils/from-flat-object-metadata-to-object-metadata-dto.util';
+import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
+
+type InlinedObjectFieldSummary = {
+ id: string;
+ name: string;
+ type: FieldMetadataType;
+ label: string;
+};
+
+const OBJECT_STRIP_WHEN_NULLISH = [
+ 'overrides',
+ 'color',
+ 'duplicateCriteria',
+ 'shortcut',
+ 'imageIdentifierFieldMetadataId',
+ 'description',
+ 'icon',
+];
+
+const getObjectMetadataInputSchema = z.object({
+ id: z.uuid().optional().describe('Object ID. Returns one object if set.'),
+ objectName: z
+ .string()
+ .optional()
+ .describe(
+ 'Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Lets you locate an object by name in one call without scanning the full list.',
+ ),
+ includeFields: z
+ .boolean()
+ .default(false)
+ .describe(
+ 'When true, each returned object includes its fields as a compact array of {id, name, type, label}. Use this to fetch an object and all the field ids you need in a single call (e.g. before building a dashboard) instead of a separate get_field_metadata call.',
+ ),
+ includeFullSystemObjects: z
+ .boolean()
+ .default(false)
+ .describe(
+ "Keep false (default) for listing or locating objects — system objects then return as compact {id, nameSingular, namePlural}, which is enough to find an object and read its id. Only set true when you specifically need a system object's full configuration (e.g. building a relation to workspaceMember).",
+ ),
+ limit: z
+ .number()
+ .int()
+ .min(1)
+ .max(100)
+ .default(100)
+ .describe('Max objects to return.'),
+});
+
+@DefineTool({
+ name: 'get_object_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description:
+ "List object metadata, returned as { objects: [...] } in the result. Filter to a single object by id or objectName (singular or plural). Set includeFields to also return each object's fields ({id, name, type, label}) — enough to build a dashboard or view without a separate get_field_metadata call. System objects are otherwise returned as compact {id, nameSingular, namePlural}. Keep includeFullSystemObjects at its default (false); only set it true when you specifically need a system object's full configuration.",
+})
+export class GetObjectMetadataTool extends BaseTool<
+ typeof getObjectMetadataInputSchema
+> {
+ readonly inputSchema = getObjectMetadataInputSchema;
+
+ constructor(
+ private readonly objectMetadataService: ObjectMetadataService,
+ private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
+ ) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof getObjectMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const flatObjectMetadatas =
+ await this.objectMetadataService.findManyWithinWorkspace(workspaceId, {
+ ...(input.id
+ ? { where: { id: input.id } }
+ : input.objectName
+ ? {
+ where: [
+ { nameSingular: input.objectName },
+ { namePlural: input.objectName },
+ ],
+ }
+ : {}),
+ take: input.limit ?? 100,
+ });
+
+ const fieldsByObjectId = input.includeFields
+ ? await this.buildFieldsByObjectId(workspaceId)
+ : undefined;
+
+ const objects = flatObjectMetadatas.map((flatObjectMetadata) => {
+ const dto = fromFlatObjectMetadataToObjectMetadataDto(flatObjectMetadata);
+
+ const fields = fieldsByObjectId?.get(dto.id) ?? [];
+
+ if (dto.isSystem && !input.includeFullSystemObjects) {
+ return {
+ id: dto.id,
+ nameSingular: dto.nameSingular,
+ namePlural: dto.namePlural,
+ ...(input.includeFields ? { fields } : {}),
+ };
+ }
+
+ return compactMetadataOutput(
+ {
+ ...dto,
+ ...(input.includeFields ? { fields } : {}),
+ },
+ { stripWhenNullish: OBJECT_STRIP_WHEN_NULLISH },
+ );
+ });
+
+ return {
+ success: true,
+ message: `Found ${objects.length} object(s).`,
+ result: { objects },
+ };
+ }
+
+ private async buildFieldsByObjectId(
+ workspaceId: string,
+ ): Promise<Map<string, InlinedObjectFieldSummary[]>> {
+ const { flatFieldMetadataMaps } =
+ await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+ {
+ workspaceId,
+ flatMapsKeys: ['flatFieldMetadataMaps'],
+ },
+ );
+
+ const fieldsByObjectId = new Map<string, InlinedObjectFieldSummary[]>();
+
+ for (const fieldMetadata of Object.values(
+ flatFieldMetadataMaps.byUniversalIdentifier,
+ )) {
+ if (
+ !isDefined(fieldMetadata) ||
+ METADATA_TOOL_EXCLUDED_FIELD_NAMES.has(fieldMetadata.name)
+ ) {
+ continue;
+ }
+
+ const existing =
+ fieldsByObjectId.get(fieldMetadata.objectMetadataId) ?? [];
+
+ existing.push({
+ id: fieldMetadata.id,
+ name: fieldMetadata.name,
+ type: fieldMetadata.type,
+ label: fieldMetadata.label ?? fieldMetadata.name,
+ });
+ fieldsByObjectId.set(fieldMetadata.objectMetadataId, existing);
+ }
+
+ return fieldsByObjectId;
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/metadata-tools.module.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/metadata-tools.module.ts
new file mode 100644
index 00000000000..650435bf760
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/metadata-tools.module.ts
@@ -0,0 +1,54 @@
+import { Module } from '@nestjs/common';
+
+import { FieldMetadataModule } from 'src/engine/metadata-modules/field-metadata/field-metadata.module';
+import { CreateFieldMetadataTool } from 'src/engine/metadata-modules/field-metadata/tools/create-field-metadata.tool';
+import { CreateManyFieldMetadataTool } from 'src/engine/metadata-modules/field-metadata/tools/create-many-field-metadata.tool';
+import { CreateManyRelationFieldsTool } from 'src/engine/metadata-modules/field-metadata/tools/create-many-relation-fields.tool';
+import { DeleteFieldMetadataTool } from 'src/engine/metadata-modules/field-metadata/tools/delete-field-metadata.tool';
+import { GetFieldMetadataTool } from 'src/engine/metadata-modules/field-metadata/tools/get-field-metadata.tool';
+import { UpdateFieldMetadataTool } from 'src/engine/metadata-modules/field-metadata/tools/update-field-metadata.tool';
+import { UpdateManyFieldMetadataTool } from 'src/engine/metadata-modules/field-metadata/tools/update-many-field-metadata.tool';
+import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
+import { ObjectMetadataModule } from 'src/engine/metadata-modules/object-metadata/object-metadata.module';
+import { CreateManyObjectMetadataTool } from 'src/engine/metadata-modules/object-metadata/tools/create-many-object-metadata.tool';
+import { CreateObjectMetadataTool } from 'src/engine/metadata-modules/object-metadata/tools/create-object-metadata.tool';
+import { DeleteObjectMetadataTool } from 'src/engine/metadata-modules/object-metadata/tools/delete-object-metadata.tool';
+import { GetObjectMetadataTool } from 'src/engine/metadata-modules/object-metadata/tools/get-object-metadata.tool';
+import { MetadataToolIdentifierService } from 'src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service';
+import { UpdateManyObjectMetadataTool } from 'src/engine/metadata-modules/object-metadata/tools/update-many-object-metadata.tool';
+import { UpdateObjectMetadataTool } from 'src/engine/metadata-modules/object-metadata/tools/update-object-metadata.tool';
+import { CreateValidationRuleTool } from 'src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool';
+import { GetValidationRulesTool } from 'src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool';
+import { UpdateValidationRuleTool } from 'src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool';
+import { ValidateValidationRuleExpressionTool } from 'src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool';
+import { ValidationRuleModule } from 'src/engine/metadata-modules/validation-rule/validation-rule.module';
+
+@Module({
+ imports: [
+ ObjectMetadataModule,
+ FieldMetadataModule,
+ ValidationRuleModule,
+ WorkspaceManyOrAllFlatEntityMapsCacheModule,
+ ],
+ providers: [
+ MetadataToolIdentifierService,
+ GetObjectMetadataTool,
+ CreateObjectMetadataTool,
+ UpdateObjectMetadataTool,
+ DeleteObjectMetadataTool,
+ CreateManyObjectMetadataTool,
+ UpdateManyObjectMetadataTool,
+ GetFieldMetadataTool,
+ CreateFieldMetadataTool,
+ UpdateFieldMetadataTool,
+ DeleteFieldMetadataTool,
+ CreateManyFieldMetadataTool,
+ UpdateManyFieldMetadataTool,
+ CreateManyRelationFieldsTool,
+ GetValidationRulesTool,
+ ValidateValidationRuleExpressionTool,
+ CreateValidationRuleTool,
+ UpdateValidationRuleTool,
+ ],
+})
+export class MetadataToolsModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/object-metadata-tools.factory.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/object-metadata-tools.factory.ts
deleted file mode 100644
index 7e14e548044..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/object-metadata-tools.factory.ts
+++ /dev/null
@@ -1,402 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-import { type FieldMetadataType } from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
-import { z } from 'zod';
-
-import { METADATA_TOOL_EXCLUDED_FIELD_NAMES } from 'src/engine/core-modules/tool-provider/constants/metadata-tool-excluded-field-names.constant';
-import { compactMetadataOutput } from 'src/engine/core-modules/tool-provider/utils/compact-metadata-output.util';
-import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
-import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
-import { fromFlatObjectMetadataToObjectMetadataDto } from 'src/engine/metadata-modules/flat-object-metadata/utils/from-flat-object-metadata-to-object-metadata-dto.util';
-import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
-
-type InlinedObjectFieldSummary = {
- id: string;
- name: string;
- type: FieldMetadataType;
- label: string;
-};
-
-const OBJECT_STRIP_WHEN_NULLISH = [
- 'overrides',
- 'color',
- 'duplicateCriteria',
- 'shortcut',
- 'imageIdentifierFieldMetadataId',
- 'description',
- 'icon',
-];
-
-const GetObjectMetadataInputSchema = z.object({
- id: z.uuid().optional().describe('Object ID. Returns one object if set.'),
- objectName: z
- .string()
- .optional()
- .describe(
- 'Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Lets you locate an object by name in one call without scanning the full list.',
- ),
- includeFields: z
- .boolean()
- .default(false)
- .describe(
- 'When true, each returned object includes its fields as a compact array of {id, name, type, label}. Use this to fetch an object and all the field ids you need in a single call (e.g. before building a dashboard) instead of a separate get_field_metadata call.',
- ),
- includeFullSystemObjects: z
- .boolean()
- .default(false)
- .describe(
- "Keep false (default) for listing or locating objects — system objects then return as compact {id, nameSingular, namePlural}, which is enough to find an object and read its id. Only set true when you specifically need a system object's full configuration (e.g. building a relation to workspaceMember).",
- ),
- limit: z
- .number()
- .int()
- .min(1)
- .max(100)
- .default(100)
- .describe('Max objects to return.'),
-});
-
-const CreateObjectMetadataInputSchema = z.object({
- nameSingular: z.string().describe('Singular name (e.g. "company")'),
- namePlural: z.string().describe('Plural name (e.g. "companies")'),
- labelSingular: z.string().describe('Singular label (e.g. "Company")'),
- labelPlural: z.string().describe('Plural label (e.g. "Companies")'),
- description: z.string().optional().describe('Description'),
- icon: z
- .string()
- .optional()
- .describe(
- 'Tabler icon name, PascalCase with "Icon" prefix (e.g. IconBuildingSkyscraper, IconPaw, IconTargetArrow). Always set one matching what the object represents.',
- ),
- shortcut: z.string().optional().describe('Keyboard shortcut'),
- isRemote: z.boolean().optional().describe('Remote object'),
- isLabelSyncedWithName: z
- .boolean()
- .optional()
- .describe('Sync label with name'),
-});
-
-const UpdateObjectMetadataInputSchema = z.object({
- id: z.uuid().describe('Object ID'),
- labelSingular: z.string().optional().describe('Singular label'),
- labelPlural: z.string().optional().describe('Plural label'),
- nameSingular: z.string().optional().describe('Singular name'),
- namePlural: z.string().optional().describe('Plural name'),
- description: z.string().optional().describe('Description'),
- icon: z
- .string()
- .optional()
- .describe('Tabler icon name (e.g. IconBuildingSkyscraper)'),
- shortcut: z.string().optional().describe('Keyboard shortcut'),
- isActive: z.boolean().optional().describe('Active state'),
- labelIdentifierFieldMetadataId: z
- .string()
- .uuid()
- .optional()
- .describe('Label identifier field ID'),
- imageIdentifierFieldMetadataId: z
- .string()
- .uuid()
- .optional()
- .describe('Image identifier field ID'),
- isLabelSyncedWithName: z
- .boolean()
- .optional()
- .describe('Sync label with name'),
-});
-
-const DeleteObjectMetadataInputSchema = z.object({
- id: z.string().uuid().describe('Object ID'),
-});
-
-const CreateManyObjectMetadataInputSchema = z.object({
- objects: z
- .array(CreateObjectMetadataInputSchema)
- .min(1)
- .max(20)
- .describe('Objects to create (max 20).'),
-});
-
-const UpdateManyObjectMetadataInputSchema = z.object({
- objects: z
- .array(UpdateObjectMetadataInputSchema)
- .min(1)
- .max(20)
- .describe('Objects to update (max 20).'),
-});
-
-@Injectable()
-export class ObjectMetadataToolsFactory {
- constructor(
- private readonly objectMetadataService: ObjectMetadataService,
- private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
- ) {}
-
- private async buildFieldsByObjectId(
- workspaceId: string,
- ): Promise<Map<string, InlinedObjectFieldSummary[]>> {
- const { flatFieldMetadataMaps } =
- await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
- {
- workspaceId,
- flatMapsKeys: ['flatFieldMetadataMaps'],
- },
- );
-
- const fieldsByObjectId = new Map<string, InlinedObjectFieldSummary[]>();
-
- for (const fieldMetadata of Object.values(
- flatFieldMetadataMaps.byUniversalIdentifier,
- )) {
- if (
- !isDefined(fieldMetadata) ||
- METADATA_TOOL_EXCLUDED_FIELD_NAMES.has(fieldMetadata.name)
- ) {
- continue;
- }
-
- const existing =
- fieldsByObjectId.get(fieldMetadata.objectMetadataId) ?? [];
-
- existing.push({
- id: fieldMetadata.id,
- name: fieldMetadata.name,
- type: fieldMetadata.type,
- label: fieldMetadata.label ?? fieldMetadata.name,
- });
- fieldsByObjectId.set(fieldMetadata.objectMetadataId, existing);
- }
-
- return fieldsByObjectId;
- }
-
- generateTools(workspaceId: string): ToolSet {
- return {
- get_object_metadata: {
- description:
- "List object metadata as an array. Filter to a single object by id or objectName (singular or plural). Set includeFields to also return each object's fields ({id, name, type, label}) — enough to build a dashboard or view without a separate get_field_metadata call. System objects are otherwise returned as compact {id, nameSingular, namePlural}. Keep includeFullSystemObjects at its default (false); only set it true when you specifically need a system object's full configuration.",
- inputSchema: GetObjectMetadataInputSchema,
- execute: async (parameters: {
- id?: string;
- objectName?: string;
- includeFields?: boolean;
- includeFullSystemObjects?: boolean;
- limit?: number;
- }) => {
- const flatObjectMetadatas =
- await this.objectMetadataService.findManyWithinWorkspace(
- workspaceId,
- {
- ...(parameters.id
- ? { where: { id: parameters.id } }
- : parameters.objectName
- ? {
- where: [
- { nameSingular: parameters.objectName },
- { namePlural: parameters.objectName },
- ],
- }
- : {}),
- take: parameters.limit ?? 100,
- },
- );
-
- const fieldsByObjectId = parameters.includeFields
- ? await this.buildFieldsByObjectId(workspaceId)
- : undefined;
-
- return flatObjectMetadatas.map((flatObjectMetadata) => {
- const dto =
- fromFlatObjectMetadataToObjectMetadataDto(flatObjectMetadata);
-
- const fields = fieldsByObjectId?.get(dto.id) ?? [];
-
- if (dto.isSystem && !parameters.includeFullSystemObjects) {
- return {
- id: dto.id,
- nameSingular: dto.nameSingular,
- namePlural: dto.namePlural,
- ...(parameters.includeFields ? { fields } : {}),
- };
- }
-
- return compactMetadataOutput(
- {
- ...dto,
- ...(parameters.includeFields ? { fields } : {}),
- },
- { stripWhenNullish: OBJECT_STRIP_WHEN_NULLISH },
- );
- });
- },
- },
- create_object_metadata: {
- description: 'Create a new object in the workspace data model.',
- inputSchema: CreateObjectMetadataInputSchema,
- execute: async (parameters: {
- nameSingular: string;
- namePlural: string;
- labelSingular: string;
- labelPlural: string;
- description?: string;
- icon?: string;
- shortcut?: string;
- isRemote?: boolean;
- isLabelSyncedWithName?: boolean;
- }) => {
- const { icon, ...createObjectInput } = parameters;
-
- const flatObjectMetadata =
- await this.objectMetadataService.createOneObject({
- createObjectInput: {
- ...createObjectInput,
- icon: normalizeIconName(icon),
- } as Parameters<
- typeof this.objectMetadataService.createOneObject
- >[0]['createObjectInput'],
- workspaceId,
- });
-
- return {
- id: flatObjectMetadata.id,
- nameSingular: flatObjectMetadata.nameSingular,
- labelSingular: flatObjectMetadata.labelSingular,
- };
- },
- },
- update_object_metadata: {
- description:
- 'Update an object. Provide object ID and properties to change.',
- inputSchema: UpdateObjectMetadataInputSchema,
- execute: async (parameters: {
- id: string;
- labelSingular?: string;
- labelPlural?: string;
- nameSingular?: string;
- namePlural?: string;
- description?: string;
- icon?: string;
- shortcut?: string;
- isActive?: boolean;
- labelIdentifierFieldMetadataId?: string;
- imageIdentifierFieldMetadataId?: string;
- isLabelSyncedWithName?: boolean;
- }) => {
- const { id, icon, ...update } = parameters;
- const normalizedIcon = normalizeIconName(icon);
-
- const flatObjectMetadata =
- await this.objectMetadataService.updateOneObject({
- updateObjectInput: {
- id,
- update: {
- ...update,
- ...(isDefined(normalizedIcon)
- ? { icon: normalizedIcon }
- : {}),
- },
- },
- workspaceId,
- });
-
- return {
- id: flatObjectMetadata.id,
- nameSingular: flatObjectMetadata.nameSingular,
- labelSingular: flatObjectMetadata.labelSingular,
- };
- },
- },
- delete_object_metadata: {
- description: 'Delete an object by ID. Also deletes associated fields.',
- inputSchema: DeleteObjectMetadataInputSchema,
- execute: async (parameters: { id: string }) => {
- const flatObjectMetadata =
- await this.objectMetadataService.deleteOneObject({
- deleteObjectInput: { id: parameters.id },
- workspaceId,
- });
-
- return { id: flatObjectMetadata.id, success: true };
- },
- },
- create_many_object_metadata: {
- description:
- 'Create multiple objects at once. Batch version of create_object_metadata.',
- inputSchema: CreateManyObjectMetadataInputSchema,
- execute: async (parameters: {
- objects: Array<{
- nameSingular: string;
- namePlural: string;
- labelSingular: string;
- labelPlural: string;
- description?: string;
- icon?: string;
- shortcut?: string;
- isRemote?: boolean;
- isLabelSyncedWithName?: boolean;
- }>;
- }) => {
- await Promise.all(
- parameters.objects.map(async ({ icon, ...createObjectInput }) => {
- await this.objectMetadataService.createOneObject({
- createObjectInput: {
- ...createObjectInput,
- icon: normalizeIconName(icon),
- } as Parameters<
- typeof this.objectMetadataService.createOneObject
- >[0]['createObjectInput'],
- workspaceId,
- });
- }),
- );
-
- return true;
- },
- },
- update_many_object_metadata: {
- description:
- 'Update multiple objects at once. Batch version of update_object_metadata. Applies the whole batch in one migration, so a rename (nameSingular or namePlural) or a labelIdentifierFieldMetadataId change cannot share a batch with another object: send each of those as its own call.',
- inputSchema: UpdateManyObjectMetadataInputSchema,
- execute: async (parameters: {
- objects: Array<{
- id: string;
- labelSingular?: string;
- labelPlural?: string;
- nameSingular?: string;
- namePlural?: string;
- description?: string;
- icon?: string;
- shortcut?: string;
- isActive?: boolean;
- labelIdentifierFieldMetadataId?: string;
- imageIdentifierFieldMetadataId?: string;
- isLabelSyncedWithName?: boolean;
- }>;
- }) => {
- await this.objectMetadataService.updateManyObjects({
- updateObjectInputs: parameters.objects.map(
- ({ id, icon, ...update }) => {
- const normalizedIcon = normalizeIconName(icon);
-
- return {
- id,
- update: {
- ...update,
- ...(isDefined(normalizedIcon)
- ? { icon: normalizedIcon }
- : {}),
- },
- };
- },
- ),
- workspaceId,
- });
-
- return true;
- },
- },
- };
- }
-}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/schemas/create-object-metadata-input.schema.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/schemas/create-object-metadata-input.schema.ts
new file mode 100644
index 00000000000..b570e736da7
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/schemas/create-object-metadata-input.schema.ts
@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const createObjectMetadataInputSchema = z.object({
+ nameSingular: z.string().describe('Singular name (e.g. "company")'),
+ namePlural: z.string().describe('Plural name (e.g. "companies")'),
+ labelSingular: z.string().describe('Singular label (e.g. "Company")'),
+ labelPlural: z.string().describe('Plural label (e.g. "Companies")'),
+ description: z.string().optional().describe('Description'),
+ icon: z
+ .string()
+ .optional()
+ .describe(
+ 'Tabler icon name, PascalCase with "Icon" prefix (e.g. IconBuildingSkyscraper, IconPaw, IconTargetArrow). Always set one matching what the object represents.',
+ ),
+ shortcut: z.string().optional().describe('Keyboard shortcut'),
+ isRemote: z.boolean().optional().describe('Remote object'),
+ isLabelSyncedWithName: z
+ .boolean()
+ .optional()
+ .describe('Sync label with name'),
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/schemas/update-object-metadata-input.schema.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/schemas/update-object-metadata-input.schema.ts
new file mode 100644
index 00000000000..21bfc4cc5d5
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/schemas/update-object-metadata-input.schema.ts
@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+export const updateObjectMetadataInputSchema = z.object({
+ id: z.uuid().describe('Object ID'),
+ labelSingular: z.string().optional().describe('Singular label'),
+ labelPlural: z.string().optional().describe('Plural label'),
+ nameSingular: z.string().optional().describe('Singular name'),
+ namePlural: z.string().optional().describe('Plural name'),
+ description: z.string().optional().describe('Description'),
+ icon: z
+ .string()
+ .optional()
+ .describe('Tabler icon name (e.g. IconBuildingSkyscraper)'),
+ shortcut: z.string().optional().describe('Keyboard shortcut'),
+ isActive: z.boolean().optional().describe('Active state'),
+ labelIdentifierFieldMetadataId: z
+ .string()
+ .uuid()
+ .optional()
+ .describe('Label identifier field ID'),
+ imageIdentifierFieldMetadataId: z
+ .string()
+ .uuid()
+ .optional()
+ .describe('Image identifier field ID'),
+ isLabelSyncedWithName: z
+ .boolean()
+ .optional()
+ .describe('Sync label with name'),
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service.ts
new file mode 100644
index 00000000000..99d528e6527
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service.ts
@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+
+import { isDefined } from 'twenty-shared/utils';
+
+import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
+import { getObjectMetadataIdByName } from 'src/engine/metadata-modules/flat-object-metadata/utils/get-object-metadata-id-by-name.util';
+import {
+ ObjectMetadataException,
+ ObjectMetadataExceptionCode,
+} from 'src/engine/metadata-modules/object-metadata/object-metadata.exception';
+
+@Injectable()
+export class MetadataToolIdentifierService {
+ constructor(
+ private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
+ ) {}
+
+ async getObjectMetadataIdOrThrow({
+ workspaceId,
+ objectName,
+ }: {
+ workspaceId: string;
+ objectName: string;
+ }): Promise<string> {
+ const { flatObjectMetadataMaps } =
+ await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+ {
+ workspaceId,
+ flatMapsKeys: ['flatObjectMetadataMaps'],
+ },
+ );
+
+ const objectMetadataId = getObjectMetadataIdByName({
+ flatObjectMetadataMaps,
+ objectName,
+ });
+
+ if (!isDefined(objectMetadataId)) {
+ throw new ObjectMetadataException(
+ `Object "${objectName}" not found. Use get_object_metadata to list available objects.`,
+ ObjectMetadataExceptionCode.OBJECT_METADATA_NOT_FOUND,
+ );
+ }
+
+ return objectMetadataId;
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/update-many-object-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/update-many-object-metadata.tool.ts
new file mode 100644
index 00000000000..39fd4877a01
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/update-many-object-metadata.tool.ts
@@ -0,0 +1,65 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { isDefined } from 'twenty-shared/utils';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
+import { updateObjectMetadataInputSchema } from 'src/engine/metadata-modules/object-metadata/tools/schemas/update-object-metadata-input.schema';
+
+const updateManyObjectMetadataInputSchema = z.object({
+ objects: z
+ .array(updateObjectMetadataInputSchema)
+ .min(1)
+ .max(20)
+ .describe('Objects to update (max 20).'),
+});
+
+@DefineTool({
+ name: 'update_many_object_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description:
+ 'Update multiple objects at once. Batch version of update_object_metadata. Applies the whole batch in one migration, so a rename (nameSingular or namePlural) or a labelIdentifierFieldMetadataId change cannot share a batch with another object: send each of those as its own call.',
+})
+export class UpdateManyObjectMetadataTool extends BaseTool<
+ typeof updateManyObjectMetadataInputSchema
+> {
+ readonly inputSchema = updateManyObjectMetadataInputSchema;
+
+ constructor(private readonly objectMetadataService: ObjectMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof updateManyObjectMetadataInputSchema
+ >): Promise<ToolOutput> {
+ await this.objectMetadataService.updateManyObjects({
+ updateObjectInputs: input.objects.map(({ id, icon, ...update }) => {
+ const normalizedIcon = normalizeIconName(icon);
+
+ return {
+ id,
+ update: {
+ ...update,
+ ...(isDefined(normalizedIcon) ? { icon: normalizedIcon } : {}),
+ },
+ };
+ }),
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Updated ${input.objects.length} object(s).`,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/update-object-metadata.tool.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/update-object-metadata.tool.ts
new file mode 100644
index 00000000000..32fb7881208
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/tools/update-object-metadata.tool.ts
@@ -0,0 +1,61 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { isDefined } from 'twenty-shared/utils';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { normalizeIconName } from 'src/engine/core-modules/tool-provider/utils/normalize-icon-name.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
+import { updateObjectMetadataInputSchema } from 'src/engine/metadata-modules/object-metadata/tools/schemas/update-object-metadata-input.schema';
+
+@DefineTool({
+ name: 'update_object_metadata',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ icon: 'IconSettings',
+ description: 'Update an object. Provide object ID and properties to change.',
+})
+export class UpdateObjectMetadataTool extends BaseTool<
+ typeof updateObjectMetadataInputSchema
+> {
+ readonly inputSchema = updateObjectMetadataInputSchema;
+
+ constructor(private readonly objectMetadataService: ObjectMetadataService) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof updateObjectMetadataInputSchema
+ >): Promise<ToolOutput> {
+ const { id, icon, ...update } = input;
+ const normalizedIcon = normalizeIconName(icon);
+
+ const flatObjectMetadata = await this.objectMetadataService.updateOneObject(
+ {
+ updateObjectInput: {
+ id,
+ update: {
+ ...update,
+ ...(isDefined(normalizedIcon) ? { icon: normalizedIcon } : {}),
+ },
+ },
+ workspaceId,
+ },
+ );
+
+ return {
+ success: true,
+ message: `Updated the object "${flatObjectMetadata.nameSingular}".`,
+ result: {
+ id: flatObjectMetadata.id,
+ nameSingular: flatObjectMetadata.nameSingular,
+ labelSingular: flatObjectMetadata.labelSingular,
+ },
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-message-description.constant.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-message-description.constant.ts
new file mode 100644
index 00000000000..d1f8963ae6f
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-message-description.constant.ts
@@ -0,0 +1,4 @@
+/* @license Enterprise */
+
+export const VALIDATION_RULE_MESSAGE_DESCRIPTION =
+ 'Message shown to the person saving the record when the expression is false.';
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-object-name-description.constant.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-object-name-description.constant.ts
new file mode 100644
index 00000000000..36ea25eb915
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-object-name-description.constant.ts
@@ -0,0 +1,4 @@
+/* @license Enterprise */
+
+export const VALIDATION_RULE_OBJECT_NAME_DESCRIPTION =
+ 'Object name, singular or plural (e.g. "company" or "companies").';
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts
new file mode 100644
index 00000000000..8f9b0338d9f
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/create-validation-rule.tool.ts
@@ -0,0 +1,81 @@
+/* @license Enterprise */
+
+import { ToolCategory } from 'twenty-shared/ai';
+import {
+ PermissionFlagType,
+ VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION,
+} from 'twenty-shared/constants';
+import { FeatureFlagKey } from 'twenty-shared/types';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { MetadataToolIdentifierService } from 'src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service';
+import { type ValidationRuleDTO } from 'src/engine/metadata-modules/validation-rule/dtos/validation-rule.dto';
+import { VALIDATION_RULE_MESSAGE_DESCRIPTION } from 'src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-message-description.constant';
+import { VALIDATION_RULE_OBJECT_NAME_DESCRIPTION } from 'src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-object-name-description.constant';
+import { ValidationRuleService } from 'src/engine/metadata-modules/validation-rule/validation-rule.service';
+
+const createValidationRuleInputSchema = z.object({
+ objectName: z.string().describe(VALIDATION_RULE_OBJECT_NAME_DESCRIPTION),
+ name: z.string().describe('Short rule name'),
+ expression: z
+ .string()
+ .describe(VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION),
+ message: z.string().describe(VALIDATION_RULE_MESSAGE_DESCRIPTION),
+ errorFieldMetadataId: z
+ .uuid()
+ .optional()
+ .describe(
+ 'ID of the field the message is shown on. Omit to show it on the whole record.',
+ ),
+});
+
+@DefineTool({
+ name: 'create_validation_rule',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
+ icon: 'IconSettings',
+ description:
+ 'Create a validation rule on an object. An invalid expression is rejected with the reason. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), they mean that rule: update it with update_validation_rule instead of creating another one.',
+})
+export class CreateValidationRuleTool extends BaseTool<
+ typeof createValidationRuleInputSchema
+> {
+ readonly inputSchema = createValidationRuleInputSchema;
+
+ constructor(
+ private readonly validationRuleService: ValidationRuleService,
+ private readonly metadataToolIdentifierService: MetadataToolIdentifierService,
+ ) {
+ super();
+ }
+
+ async execute({
+ input: { objectName, ...input },
+ context: { workspaceId },
+ }: ToolExecuteArgs<typeof createValidationRuleInputSchema>): Promise<
+ ToolOutput<ValidationRuleDTO>
+ > {
+ const validationRule = await this.validationRuleService.create({
+ input: {
+ ...input,
+ objectMetadataId:
+ await this.metadataToolIdentifierService.getObjectMetadataIdOrThrow({
+ workspaceId,
+ objectName,
+ }),
+ },
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Created the validation rule "${validationRule.name}".`,
+ result: validationRule,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts
new file mode 100644
index 00000000000..fe4801d1025
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/get-validation-rules.tool.ts
@@ -0,0 +1,64 @@
+/* @license Enterprise */
+
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
+import { FeatureFlagKey } from 'twenty-shared/types';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { MetadataToolIdentifierService } from 'src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service';
+import { type ValidationRuleDTO } from 'src/engine/metadata-modules/validation-rule/dtos/validation-rule.dto';
+import { VALIDATION_RULE_OBJECT_NAME_DESCRIPTION } from 'src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-object-name-description.constant';
+import { ValidationRuleService } from 'src/engine/metadata-modules/validation-rule/validation-rule.service';
+
+const getValidationRulesInputSchema = z.object({
+ objectName: z.string().describe(VALIDATION_RULE_OBJECT_NAME_DESCRIPTION),
+});
+
+@DefineTool({
+ name: 'get_validation_rules',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
+ icon: 'IconSettings',
+ description:
+ 'List the validation rules of an object: conditions a record must meet to be saved.',
+})
+export class GetValidationRulesTool extends BaseTool<
+ typeof getValidationRulesInputSchema
+> {
+ readonly inputSchema = getValidationRulesInputSchema;
+
+ constructor(
+ private readonly validationRuleService: ValidationRuleService,
+ private readonly metadataToolIdentifierService: MetadataToolIdentifierService,
+ ) {
+ super();
+ }
+
+ async execute({
+ input,
+ context: { workspaceId },
+ }: ToolExecuteArgs<typeof getValidationRulesInputSchema>): Promise<
+ ToolOutput<ValidationRuleDTO[]>
+ > {
+ const validationRules =
+ await this.validationRuleService.findByObjectMetadataId({
+ objectMetadataId:
+ await this.metadataToolIdentifierService.getObjectMetadataIdOrThrow({
+ workspaceId,
+ objectName: input.objectName,
+ }),
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Found ${validationRules.length} validation rule(s).`,
+ result: validationRules,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts
new file mode 100644
index 00000000000..08d4e7d423f
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/update-validation-rule.tool.ts
@@ -0,0 +1,75 @@
+/* @license Enterprise */
+
+import { ToolCategory } from 'twenty-shared/ai';
+import {
+ PermissionFlagType,
+ VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION,
+} from 'twenty-shared/constants';
+import { FeatureFlagKey } from 'twenty-shared/types';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { type ValidationRuleDTO } from 'src/engine/metadata-modules/validation-rule/dtos/validation-rule.dto';
+import { VALIDATION_RULE_MESSAGE_DESCRIPTION } from 'src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-message-description.constant';
+import { ValidationRuleService } from 'src/engine/metadata-modules/validation-rule/validation-rule.service';
+
+const updateValidationRuleInputSchema = z.object({
+ id: z.uuid().describe('Validation rule ID'),
+ name: z.string().optional().describe('Short rule name'),
+ expression: z
+ .string()
+ .optional()
+ .describe(VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION),
+ message: z.string().optional().describe(VALIDATION_RULE_MESSAGE_DESCRIPTION),
+ errorFieldMetadataId: z
+ .uuid()
+ .nullable()
+ .optional()
+ .describe(
+ 'ID of the field the message is shown on, or null to show it on the whole record.',
+ ),
+ isActive: z
+ .boolean()
+ .optional()
+ .describe('Set false to turn the rule off without deleting it.'),
+});
+
+@DefineTool({
+ name: 'update_validation_rule',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
+ icon: 'IconSettings',
+ description:
+ 'Update a validation rule. Only the provided properties change. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), requests about a rule are about that one. An active rule rejects an invalid expression with the reason; an inactive rule only checks it when activated, so check it first with validate_validation_rule_expression. Keep the rule inactive unless the user asks to activate it.',
+})
+export class UpdateValidationRuleTool extends BaseTool<
+ typeof updateValidationRuleInputSchema
+> {
+ readonly inputSchema = updateValidationRuleInputSchema;
+
+ constructor(private readonly validationRuleService: ValidationRuleService) {
+ super();
+ }
+
+ async execute({
+ input: { id, ...update },
+ context: { workspaceId },
+ }: ToolExecuteArgs<typeof updateValidationRuleInputSchema>): Promise<
+ ToolOutput<ValidationRuleDTO>
+ > {
+ const validationRule = await this.validationRuleService.update({
+ input: { id, update },
+ workspaceId,
+ });
+
+ return {
+ success: true,
+ message: `Updated the validation rule "${validationRule.name}".`,
+ result: validationRule,
+ };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts
new file mode 100644
index 00000000000..45c5b53f6f5
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validate-validation-rule-expression.tool.ts
@@ -0,0 +1,65 @@
+/* @license Enterprise */
+
+import { ToolCategory } from 'twenty-shared/ai';
+import {
+ PermissionFlagType,
+ VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION,
+} from 'twenty-shared/constants';
+import { FeatureFlagKey } from 'twenty-shared/types';
+import { z } from 'zod';
+
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { MetadataToolIdentifierService } from 'src/engine/metadata-modules/object-metadata/tools/services/metadata-tool-identifier.service';
+import { VALIDATION_RULE_OBJECT_NAME_DESCRIPTION } from 'src/engine/metadata-modules/validation-rule/tools/constants/validation-rule-object-name-description.constant';
+import { ValidationRuleService } from 'src/engine/metadata-modules/validation-rule/validation-rule.service';
+
+const validateValidationRuleExpressionInputSchema = z.object({
+ objectName: z.string().describe(VALIDATION_RULE_OBJECT_NAME_DESCRIPTION),
+ expression: z
+ .string()
+ .describe(VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION),
+});
+
+@DefineTool({
+ name: 'validate_validation_rule_expression',
+ category: ToolCategory.METADATA,
+ requiredPermissionFlags: [PermissionFlagType.DATA_MODEL],
+ requiredFeatureFlags: [FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED],
+ icon: 'IconSettings',
+ description:
+ 'Check a validation rule expression against an object without saving anything. An invalid expression is rejected with the reason.',
+})
+export class ValidateValidationRuleExpressionTool extends BaseTool<
+ typeof validateValidationRuleExpressionInputSchema
+> {
+ readonly inputSchema = validateValidationRuleExpressionInputSchema;
+
+ constructor(
+ private readonly validationRuleService: ValidationRuleService,
+ private readonly metadataToolIdentifierService: MetadataToolIdentifierService,
+ ) {
+ super();
+ }
+
+ async execute({
+ input: { objectName, expression },
+ context: { workspaceId },
+ }: ToolExecuteArgs<
+ typeof validateValidationRuleExpressionInputSchema
+ >): Promise<ToolOutput> {
+ await this.validationRuleService.validateExpressionOrThrow({
+ objectMetadataId:
+ await this.metadataToolIdentifierService.getObjectMetadataIdOrThrow({
+ workspaceId,
+ objectName,
+ }),
+ expression,
+ workspaceId,
+ });
+
+ return { success: true, message: 'The expression is valid.' };
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validation-rule-tools.factory.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validation-rule-tools.factory.ts
deleted file mode 100644
index cb86d64ea53..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/tools/validation-rule-tools.factory.ts
+++ /dev/null
@@ -1,219 +0,0 @@
-/* @license Enterprise */
-
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-import { VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION } from 'twenty-shared/constants';
-import { isDefined } from 'twenty-shared/utils';
-import { z } from 'zod';
-
-import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
-import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
-import { getObjectMetadataIdByName } from 'src/engine/metadata-modules/flat-object-metadata/utils/get-object-metadata-id-by-name.util';
-import {
- ObjectMetadataException,
- ObjectMetadataExceptionCode,
-} from 'src/engine/metadata-modules/object-metadata/object-metadata.exception';
-import { type ValidationRuleDTO } from 'src/engine/metadata-modules/validation-rule/dtos/validation-rule.dto';
-import { ValidationRuleService } from 'src/engine/metadata-modules/validation-rule/validation-rule.service';
-
-const OBJECT_NAME_DESCRIPTION =
- 'Object name, singular or plural (e.g. "company" or "companies").';
-
-const MESSAGE_DESCRIPTION =
- 'Message shown to the person saving the record when the expression is false.';
-
-const GetValidationRulesInputSchema = z.object({
- objectName: z.string().describe(OBJECT_NAME_DESCRIPTION),
-});
-
-const ValidateValidationRuleExpressionInputSchema = z.object({
- objectName: z.string().describe(OBJECT_NAME_DESCRIPTION),
- expression: z
- .string()
- .describe(VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION),
-});
-
-const CreateValidationRuleInputSchema = z.object({
- objectName: z.string().describe(OBJECT_NAME_DESCRIPTION),
- name: z.string().describe('Short rule name'),
- expression: z
- .string()
- .describe(VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION),
- message: z.string().describe(MESSAGE_DESCRIPTION),
- errorFieldMetadataId: z
- .uuid()
- .optional()
- .describe(
- 'ID of the field the message is shown on. Omit to show it on the whole record.',
- ),
-});
-
-const UpdateValidationRuleInputSchema = z.object({
- id: z.uuid().describe('Validation rule ID'),
- name: z.string().optional().describe('Short rule name'),
- expression: z
- .string()
- .optional()
- .describe(VALIDATION_RULE_EXPRESSION_SYNTAX_DESCRIPTION),
- message: z.string().optional().describe(MESSAGE_DESCRIPTION),
- errorFieldMetadataId: z
- .uuid()
- .nullable()
- .optional()
- .describe(
- 'ID of the field the message is shown on, or null to show it on the whole record.',
- ),
- isActive: z
- .boolean()
- .optional()
- .describe('Set false to turn the rule off without deleting it.'),
-});
-
-@Injectable()
-export class ValidationRuleToolsFactory {
- constructor(
- private readonly validationRuleService: ValidationRuleService,
- private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
- ) {}
-
- private async getObjectMetadataIdOrThrow({
- workspaceId,
- objectName,
- }: {
- workspaceId: string;
- objectName: string;
- }): Promise<string> {
- const { flatObjectMetadataMaps } =
- await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
- {
- workspaceId,
- flatMapsKeys: ['flatObjectMetadataMaps'],
- },
- );
-
- const objectMetadataId = getObjectMetadataIdByName({
- flatObjectMetadataMaps,
- objectName,
- });
-
- if (!isDefined(objectMetadataId)) {
- throw new ObjectMetadataException(
- `Object "${objectName}" not found. Use get_object_metadata to list available objects.`,
- ObjectMetadataExceptionCode.OBJECT_METADATA_NOT_FOUND,
- );
- }
-
- return objectMetadataId;
- }
-
- generateTools(workspaceId: string): ToolSet {
- return {
- get_validation_rules: {
- description:
- 'List the validation rules of an object: conditions a record must meet to be saved.',
- inputSchema: GetValidationRulesInputSchema,
- execute: async (parameters: {
- objectName: string;
- }): Promise<ToolOutput<ValidationRuleDTO[]>> => {
- const validationRules =
- await this.validationRuleService.findByObjectMetadataId({
- objectMetadataId: await this.getObjectMetadataIdOrThrow({
- workspaceId,
- objectName: parameters.objectName,
- }),
- workspaceId,
- });
-
- return {
- success: true,
- message: `Found ${validationRules.length} validation rule(s).`,
- result: validationRules,
- };
- },
- },
- validate_validation_rule_expression: {
- description:
- 'Check a validation rule expression against an object without saving anything. An invalid expression is rejected with the reason.',
- inputSchema: ValidateValidationRuleExpressionInputSchema,
- execute: async ({
- objectName,
- expression,
- }: {
- objectName: string;
- expression: string;
- }): Promise<ToolOutput> => {
- await this.validationRuleService.validateExpressionOrThrow({
- objectMetadataId: await this.getObjectMetadataIdOrThrow({
- workspaceId,
- objectName,
- }),
- expression,
- workspaceId,
- });
-
- return { success: true, message: 'The expression is valid.' };
- },
- },
- create_validation_rule: {
- description:
- 'Create a validation rule on an object. An invalid expression is rejected with the reason. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), they mean that rule: update it with update_validation_rule instead of creating another one.',
- inputSchema: CreateValidationRuleInputSchema,
- execute: async ({
- objectName,
- ...input
- }: {
- objectName: string;
- name: string;
- expression: string;
- message: string;
- errorFieldMetadataId?: string;
- }): Promise<ToolOutput<ValidationRuleDTO>> => {
- const validationRule = await this.validationRuleService.create({
- input: {
- ...input,
- objectMetadataId: await this.getObjectMetadataIdOrThrow({
- workspaceId,
- objectName,
- }),
- },
- workspaceId,
- });
-
- return {
- success: true,
- message: `Created the validation rule "${validationRule.name}".`,
- result: validationRule,
- };
- },
- },
- update_validation_rule: {
- description:
- 'Update a validation rule. Only the provided properties change. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), requests about a rule are about that one. An active rule rejects an invalid expression with the reason; an inactive rule only checks it when activated, so check it first with validate_validation_rule_expression. Keep the rule inactive unless the user asks to activate it.',
- inputSchema: UpdateValidationRuleInputSchema,
- execute: async ({
- id,
- ...update
- }: {
- id: string;
- name?: string;
- expression?: string;
- message?: string;
- errorFieldMetadataId?: string | null;
- isActive?: boolean;
- }): Promise<ToolOutput<ValidationRuleDTO>> => {
- const validationRule = await this.validationRuleService.update({
- input: { id, update },
- workspaceId,
- });
-
- return {
- success: true,
- message: `Updated the validation rule "${validationRule.name}".`,
- result: validationRule,
- };
- },
- },
- };
- }
-}
diff --git a/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.module.ts b/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.module.ts
index cbdd4b739b7..96cdc75ad88 100644
--- a/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.module.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/validation-rule/validation-rule.module.ts
@@ -7,7 +7,6 @@ import { BillingModule } from 'src/engine/core-modules/billing/billing.module';
import { FeatureFlagModule } from 'src/engine/core-modules/feature-flag/feature-flag.module';
import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
-import { ValidationRuleToolsFactory } from 'src/engine/metadata-modules/validation-rule/tools/validation-rule-tools.factory';
import { ValidationRuleResolver } from 'src/engine/metadata-modules/validation-rule/validation-rule.resolver';
import { ValidationRuleService } from 'src/engine/metadata-modules/validation-rule/validation-rule.service';
import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace-migration/workspace-migration.module';
@@ -21,11 +20,7 @@ import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace
PermissionsModule,
WorkspaceMigrationModule,
],
- providers: [
- ValidationRuleService,
- ValidationRuleResolver,
- ValidationRuleToolsFactory,
- ],
- exports: [ValidationRuleToolsFactory],
+ providers: [ValidationRuleService, ValidationRuleResolver],
+ exports: [ValidationRuleService],
})
export class ValidationRuleModule {}
diff --git a/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts b/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts
index d6517b10116..d40a45ac4a1 100644
--- a/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts
+++ b/packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts
@@ -624,8 +624,8 @@ You help users manage their workspace data model by creating, updating, and orga
## Tool Output Format
-- **get_object_metadata** returns an array of objects. System objects (attachment, message, etc.) are returned as compact \`{id, nameSingular, namePlural}\`, which is enough to locate an object and read its id. Only pass \`includeFullSystemObjects: true\` when you specifically need a system object's full configuration (e.g. when creating relations to workspaceMember).
-- **get_field_metadata** returns an array of fields. System fields are returned as compact \`{id, name, type}\`, which is enough to know which fields exist and their types. Only pass \`includeFullSystemFields: true\` when you specifically need a system field's full configuration (settings, defaultValue, relation targets). Internal fields (searchVector, position, updatedBy) are always excluded. Null properties are omitted from non-system fields.
+- **get_object_metadata** returns its objects as an array under \`result.objects\`. System objects (attachment, message, etc.) are returned as compact \`{id, nameSingular, namePlural}\`, which is enough to locate an object and read its id. Only pass \`includeFullSystemObjects: true\` when you specifically need a system object's full configuration (e.g. when creating relations to workspaceMember).
+- **get_field_metadata** returns its fields as an array under \`result.fields\`. System fields are returned as compact \`{id, name, type}\`, which is enough to know which fields exist and their types. Only pass \`includeFullSystemFields: true\` when you specifically need a system field's full configuration (settings, defaultValue, relation targets). Internal fields (searchVector, position, updatedBy) are always excluded. Null properties are omitted from non-system fields.
## Field Types Available
- **TEXT**: Simple text fields
diff --git a/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-metadata-tools.integration-spec.ts.snap b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-metadata-tools.integration-spec.ts.snap
new file mode 100644
index 00000000000..60500c4c63a
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-metadata-tools.integration-spec.ts.snap
@@ -0,0 +1,946 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`MCP metadata tools (integration) should describe the metadata tools to the model 1`] = `
+[
+ {
+ "description": "List object metadata, returned as { objects: [...] } in the result. Filter to a single object by id or objectName (singular or plural). Set includeFields to also return each object's fields ({id, name, type, label}) — enough to build a dashboard or view without a separate get_field_metadata call. System objects are otherwise returned as compact {id, nameSingular, namePlural}. Keep includeFullSystemObjects at its default (false); only set it true when you specifically need a system object's full configuration.",
+ "inputSchema": {
+ "properties": {
+ "id": {
+ "description": "Object ID. Returns one object if set.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "includeFields": {
+ "default": false,
+ "description": "When true, each returned object includes its fields as a compact array of {id, name, type, label}. Use this to fetch an object and all the field ids you need in a single call (e.g. before building a dashboard) instead of a separate get_field_metadata call.",
+ "type": "boolean",
+ },
+ "includeFullSystemObjects": {
+ "default": false,
+ "description": "Keep false (default) for listing or locating objects — system objects then return as compact {id, nameSingular, namePlural}, which is enough to find an object and read its id. Only set true when you specifically need a system object's full configuration (e.g. building a relation to workspaceMember).",
+ "type": "boolean",
+ },
+ "limit": {
+ "default": 100,
+ "description": "Max objects to return.",
+ "type": "integer",
+ },
+ "objectName": {
+ "description": "Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Lets you locate an object by name in one call without scanning the full list.",
+ "type": "string",
+ },
+ },
+ "type": "object",
+ },
+ "name": "get_object_metadata",
+ },
+ {
+ "description": "Create a new object in the workspace data model.",
+ "inputSchema": {
+ "properties": {
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name, PascalCase with "Icon" prefix (e.g. IconBuildingSkyscraper, IconPaw, IconTargetArrow). Always set one matching what the object represents.",
+ "type": "string",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "isRemote": {
+ "description": "Remote object",
+ "type": "boolean",
+ },
+ "labelPlural": {
+ "description": "Plural label (e.g. "Companies")",
+ "type": "string",
+ },
+ "labelSingular": {
+ "description": "Singular label (e.g. "Company")",
+ "type": "string",
+ },
+ "namePlural": {
+ "description": "Plural name (e.g. "companies")",
+ "type": "string",
+ },
+ "nameSingular": {
+ "description": "Singular name (e.g. "company")",
+ "type": "string",
+ },
+ "shortcut": {
+ "description": "Keyboard shortcut",
+ "type": "string",
+ },
+ },
+ "required": [
+ "nameSingular",
+ "namePlural",
+ "labelSingular",
+ "labelPlural",
+ ],
+ "type": "object",
+ },
+ "name": "create_object_metadata",
+ },
+ {
+ "description": "Update an object. Provide object ID and properties to change.",
+ "inputSchema": {
+ "properties": {
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name (e.g. IconBuildingSkyscraper)",
+ "type": "string",
+ },
+ "id": {
+ "description": "Object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "imageIdentifierFieldMetadataId": {
+ "description": "Image identifier field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "isActive": {
+ "description": "Active state",
+ "type": "boolean",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "labelIdentifierFieldMetadataId": {
+ "description": "Label identifier field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "labelPlural": {
+ "description": "Plural label",
+ "type": "string",
+ },
+ "labelSingular": {
+ "description": "Singular label",
+ "type": "string",
+ },
+ "namePlural": {
+ "description": "Plural name",
+ "type": "string",
+ },
+ "nameSingular": {
+ "description": "Singular name",
+ "type": "string",
+ },
+ "shortcut": {
+ "description": "Keyboard shortcut",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "update_object_metadata",
+ },
+ {
+ "description": "Delete an object by ID. Also deletes associated fields.",
+ "inputSchema": {
+ "properties": {
+ "id": {
+ "description": "Object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "delete_object_metadata",
+ },
+ {
+ "description": "Create multiple objects at once. Batch version of create_object_metadata.",
+ "inputSchema": {
+ "properties": {
+ "objects": {
+ "description": "Objects to create (max 20).",
+ "items": {
+ "properties": {
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name, PascalCase with "Icon" prefix (e.g. IconBuildingSkyscraper, IconPaw, IconTargetArrow). Always set one matching what the object represents.",
+ "type": "string",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "isRemote": {
+ "description": "Remote object",
+ "type": "boolean",
+ },
+ "labelPlural": {
+ "description": "Plural label (e.g. "Companies")",
+ "type": "string",
+ },
+ "labelSingular": {
+ "description": "Singular label (e.g. "Company")",
+ "type": "string",
+ },
+ "namePlural": {
+ "description": "Plural name (e.g. "companies")",
+ "type": "string",
+ },
+ "nameSingular": {
+ "description": "Singular name (e.g. "company")",
+ "type": "string",
+ },
+ "shortcut": {
+ "description": "Keyboard shortcut",
+ "type": "string",
+ },
+ },
+ "required": [
+ "nameSingular",
+ "namePlural",
+ "labelSingular",
+ "labelPlural",
+ ],
+ "type": "object",
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array",
+ },
+ },
+ "required": [
+ "objects",
+ ],
+ "type": "object",
+ },
+ "name": "create_many_object_metadata",
+ },
+ {
+ "description": "Update multiple objects at once. Batch version of update_object_metadata. Applies the whole batch in one migration, so a rename (nameSingular or namePlural) or a labelIdentifierFieldMetadataId change cannot share a batch with another object: send each of those as its own call.",
+ "inputSchema": {
+ "properties": {
+ "objects": {
+ "description": "Objects to update (max 20).",
+ "items": {
+ "properties": {
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name (e.g. IconBuildingSkyscraper)",
+ "type": "string",
+ },
+ "id": {
+ "description": "Object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "imageIdentifierFieldMetadataId": {
+ "description": "Image identifier field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "isActive": {
+ "description": "Active state",
+ "type": "boolean",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "labelIdentifierFieldMetadataId": {
+ "description": "Label identifier field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "labelPlural": {
+ "description": "Plural label",
+ "type": "string",
+ },
+ "labelSingular": {
+ "description": "Singular label",
+ "type": "string",
+ },
+ "namePlural": {
+ "description": "Plural name",
+ "type": "string",
+ },
+ "nameSingular": {
+ "description": "Singular name",
+ "type": "string",
+ },
+ "shortcut": {
+ "description": "Keyboard shortcut",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array",
+ },
+ },
+ "required": [
+ "objects",
+ ],
+ "type": "object",
+ },
+ "name": "update_many_object_metadata",
+ },
+ {
+ "description": "Returns { fields: [...] } in the result. System fields are returned as compact {id, name, type} — enough to know which fields exist and their types. Keep includeFullSystemFields at its default (false); only set it true when you specifically need a system field's full configuration (settings, defaultValue, relation targets). Internal fields (searchVector, position, updatedBy) are excluded.",
+ "inputSchema": {
+ "properties": {
+ "id": {
+ "description": "Field ID. Returns one field if set.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "includeFullSystemFields": {
+ "default": false,
+ "description": "Keep false (default) for listing or inspecting fields — system fields then return as compact {id, name, type}, which is enough to know which fields exist and their types. Only set true when you specifically need a system field's full configuration (settings, defaultValue, relation targets).",
+ "type": "boolean",
+ },
+ "limit": {
+ "default": 100,
+ "description": "Max fields to return.",
+ "type": "integer",
+ },
+ "objectMetadataId": {
+ "description": "Filter by object ID.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "objectName": {
+ "description": "Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Convenient alternative to objectMetadataId so you do not need to resolve the object id first.",
+ "type": "string",
+ },
+ },
+ "type": "object",
+ },
+ "name": "get_field_metadata",
+ },
+ {
+ "description": "Create a new field on an object.",
+ "inputSchema": {
+ "properties": {
+ "defaultValue": {
+ "description": "Default value",
+ },
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name, PascalCase with "Icon" prefix (e.g. IconCurrencyDollar, IconCalendarTime, IconPaw). Set one matching the field meaning; falls back to a type-based default.",
+ "type": "string",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "isNullable": {
+ "description": "Nullable",
+ "type": "boolean",
+ },
+ "isRemoteCreation": {
+ "description": "Remote field creation",
+ "type": "boolean",
+ },
+ "isUnique": {
+ "description": "Unique constraint",
+ "type": "boolean",
+ },
+ "label": {
+ "description": "Display label",
+ "type": "string",
+ },
+ "name": {
+ "description": "Field name (camelCase)",
+ "type": "string",
+ },
+ "objectMetadataId": {
+ "description": "Target object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "options": {
+ "description": "SELECT/MULTI_SELECT options: [{ label, value, position, color }]. color is one of red, ruby, crimson, tomato, orange, amber, yellow, lime, grass, green, jade, mint, turquoise, cyan, sky, blue, iris, violet, purple, plum, pink, bronze, gold, brown, gray; defaults to gray when omitted.",
+ },
+ "relationCreationPayload": {
+ "description": "Required when type is RELATION. Defines the relation direction and the inverse field created on the target object.",
+ "properties": {
+ "targetFieldIcon": {
+ "description": "Tabler icon name for the inverse field (e.g. IconBuildingSkyscraper). Falls back to the relation default.",
+ "type": "string",
+ },
+ "targetFieldLabel": {
+ "description": "Display label of the inverse relation field created on the target object",
+ "type": "string",
+ },
+ "targetObjectMetadataId": {
+ "description": "Target object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "type": {
+ "description": "Relation direction from the perspective of the object the field is created on. MANY_TO_ONE: the field points to a single target record; this object owns the foreign key and gets a writable '<fieldName>Id' on its create/update inputs. Use it for 'belongs to one' fields. ONE_TO_MANY: the field is a read-only collection of target records; records are linked by writing the inverse '<fieldName>Id' on the target object.",
+ "enum": [
+ "MANY_TO_ONE",
+ "ONE_TO_MANY",
+ ],
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "targetObjectMetadataId",
+ "targetFieldLabel",
+ ],
+ "type": "object",
+ },
+ "settings": {
+ "description": "Field settings",
+ },
+ "type": {
+ "description": "Field type",
+ "enum": [
+ "ACTOR",
+ "ADDRESS",
+ "ARRAY",
+ "BOOLEAN",
+ "CURRENCY",
+ "DATE",
+ "DATE_TIME",
+ "EMAILS",
+ "FILES",
+ "FULL_NAME",
+ "LINKS",
+ "MORPH_RELATION",
+ "MULTI_SELECT",
+ "NUMBER",
+ "NUMERIC",
+ "PHONES",
+ "POSITION",
+ "RATING",
+ "RAW_JSON",
+ "RELATION",
+ "RICH_TEXT",
+ "SELECT",
+ "TEXT",
+ "TS_VECTOR",
+ "UUID",
+ ],
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectMetadataId",
+ "type",
+ "name",
+ "label",
+ ],
+ "type": "object",
+ },
+ "name": "create_field_metadata",
+ },
+ {
+ "description": "Update a field. Provide field ID and properties to change.",
+ "inputSchema": {
+ "properties": {
+ "defaultValue": {
+ "description": "Default value",
+ },
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name (e.g. IconCurrencyDollar)",
+ "type": "string",
+ },
+ "id": {
+ "description": "Field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "isActive": {
+ "description": "Active state",
+ "type": "boolean",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "isNullable": {
+ "description": "Nullable",
+ "type": "boolean",
+ },
+ "isUnique": {
+ "description": "Unique constraint",
+ "type": "boolean",
+ },
+ "label": {
+ "description": "Display label",
+ "type": "string",
+ },
+ "name": {
+ "description": "Field name",
+ "type": "string",
+ },
+ "options": {
+ "description": "SELECT/MULTI_SELECT options: [{ label, value, position, color }]. color is one of red, ruby, crimson, tomato, orange, amber, yellow, lime, grass, green, jade, mint, turquoise, cyan, sky, blue, iris, violet, purple, plum, pink, bronze, gold, brown, gray; defaults to gray when omitted.",
+ },
+ "settings": {
+ "description": "Field settings",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "update_field_metadata",
+ },
+ {
+ "description": "Delete a field by ID.",
+ "inputSchema": {
+ "properties": {
+ "id": {
+ "description": "Field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "delete_field_metadata",
+ },
+ {
+ "description": "Create multiple field metadata at once on one or more objects. More efficient than calling create_field_metadata multiple times. Each item follows the same schema as create_field_metadata.",
+ "inputSchema": {
+ "properties": {
+ "fields": {
+ "description": "Fields to create (max 20).",
+ "items": {
+ "properties": {
+ "defaultValue": {
+ "description": "Default value",
+ },
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name, PascalCase with "Icon" prefix (e.g. IconCurrencyDollar, IconCalendarTime, IconPaw). Set one matching the field meaning; falls back to a type-based default.",
+ "type": "string",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "isNullable": {
+ "description": "Nullable",
+ "type": "boolean",
+ },
+ "isRemoteCreation": {
+ "description": "Remote field creation",
+ "type": "boolean",
+ },
+ "isUnique": {
+ "description": "Unique constraint",
+ "type": "boolean",
+ },
+ "label": {
+ "description": "Display label",
+ "type": "string",
+ },
+ "name": {
+ "description": "Field name (camelCase)",
+ "type": "string",
+ },
+ "objectMetadataId": {
+ "description": "Target object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "options": {
+ "description": "SELECT/MULTI_SELECT options: [{ label, value, position, color }]. color is one of red, ruby, crimson, tomato, orange, amber, yellow, lime, grass, green, jade, mint, turquoise, cyan, sky, blue, iris, violet, purple, plum, pink, bronze, gold, brown, gray; defaults to gray when omitted.",
+ },
+ "relationCreationPayload": {
+ "description": "Required when type is RELATION. Defines the relation direction and the inverse field created on the target object.",
+ "properties": {
+ "targetFieldIcon": {
+ "description": "Tabler icon name for the inverse field (e.g. IconBuildingSkyscraper). Falls back to the relation default.",
+ "type": "string",
+ },
+ "targetFieldLabel": {
+ "description": "Display label of the inverse relation field created on the target object",
+ "type": "string",
+ },
+ "targetObjectMetadataId": {
+ "description": "Target object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "type": {
+ "description": "Relation direction from the perspective of the object the field is created on. MANY_TO_ONE: the field points to a single target record; this object owns the foreign key and gets a writable '<fieldName>Id' on its create/update inputs. Use it for 'belongs to one' fields. ONE_TO_MANY: the field is a read-only collection of target records; records are linked by writing the inverse '<fieldName>Id' on the target object.",
+ "enum": [
+ "MANY_TO_ONE",
+ "ONE_TO_MANY",
+ ],
+ "type": "string",
+ },
+ },
+ "required": [
+ "type",
+ "targetObjectMetadataId",
+ "targetFieldLabel",
+ ],
+ "type": "object",
+ },
+ "settings": {
+ "description": "Field settings",
+ },
+ "type": {
+ "description": "Field type",
+ "enum": [
+ "ACTOR",
+ "ADDRESS",
+ "ARRAY",
+ "BOOLEAN",
+ "CURRENCY",
+ "DATE",
+ "DATE_TIME",
+ "EMAILS",
+ "FILES",
+ "FULL_NAME",
+ "LINKS",
+ "MORPH_RELATION",
+ "MULTI_SELECT",
+ "NUMBER",
+ "NUMERIC",
+ "PHONES",
+ "POSITION",
+ "RATING",
+ "RAW_JSON",
+ "RELATION",
+ "RICH_TEXT",
+ "SELECT",
+ "TEXT",
+ "TS_VECTOR",
+ "UUID",
+ ],
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectMetadataId",
+ "type",
+ "name",
+ "label",
+ ],
+ "type": "object",
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array",
+ },
+ },
+ "required": [
+ "fields",
+ ],
+ "type": "object",
+ },
+ "name": "create_many_field_metadata",
+ },
+ {
+ "description": "Update multiple field metadata at once. More efficient than calling update_field_metadata multiple times. Each item must include the field ID and the properties to update.",
+ "inputSchema": {
+ "properties": {
+ "fields": {
+ "description": "Fields to update (max 20).",
+ "items": {
+ "properties": {
+ "defaultValue": {
+ "description": "Default value",
+ },
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name (e.g. IconCurrencyDollar)",
+ "type": "string",
+ },
+ "id": {
+ "description": "Field ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "isActive": {
+ "description": "Active state",
+ "type": "boolean",
+ },
+ "isLabelSyncedWithName": {
+ "description": "Sync label with name",
+ "type": "boolean",
+ },
+ "isNullable": {
+ "description": "Nullable",
+ "type": "boolean",
+ },
+ "isUnique": {
+ "description": "Unique constraint",
+ "type": "boolean",
+ },
+ "label": {
+ "description": "Display label",
+ "type": "string",
+ },
+ "name": {
+ "description": "Field name",
+ "type": "string",
+ },
+ "options": {
+ "description": "SELECT/MULTI_SELECT options: [{ label, value, position, color }]. color is one of red, ruby, crimson, tomato, orange, amber, yellow, lime, grass, green, jade, mint, turquoise, cyan, sky, blue, iris, violet, purple, plum, pink, bronze, gold, brown, gray; defaults to gray when omitted.",
+ },
+ "settings": {
+ "description": "Field settings",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array",
+ },
+ },
+ "required": [
+ "fields",
+ ],
+ "type": "object",
+ },
+ "name": "update_many_field_metadata",
+ },
+ {
+ "description": "Create multiple relation fields between objects at once.",
+ "inputSchema": {
+ "properties": {
+ "relations": {
+ "description": "Relations to create (max 20).",
+ "items": {
+ "properties": {
+ "description": {
+ "description": "Description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Tabler icon name for the relation field (e.g. IconUsers)",
+ "type": "string",
+ },
+ "label": {
+ "description": "Display label",
+ "type": "string",
+ },
+ "name": {
+ "description": "Field name (camelCase)",
+ "type": "string",
+ },
+ "objectMetadataId": {
+ "description": "Source object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "targetFieldIcon": {
+ "description": "Inverse field Tabler icon name (e.g. IconBuildingSkyscraper)",
+ "type": "string",
+ },
+ "targetFieldLabel": {
+ "description": "Inverse field label",
+ "type": "string",
+ },
+ "targetObjectMetadataId": {
+ "description": "Target object ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "type": {
+ "description": "Relation direction from the perspective of the object the field is created on. MANY_TO_ONE: the field points to a single target record; this object owns the foreign key and gets a writable '<fieldName>Id' on its create/update inputs. Use it for 'belongs to one' fields. ONE_TO_MANY: the field is a read-only collection of target records; records are linked by writing the inverse '<fieldName>Id' on the target object.",
+ "enum": [
+ "MANY_TO_ONE",
+ "ONE_TO_MANY",
+ ],
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectMetadataId",
+ "name",
+ "label",
+ "type",
+ "targetObjectMetadataId",
+ "targetFieldLabel",
+ "targetFieldIcon",
+ ],
+ "type": "object",
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array",
+ },
+ },
+ "required": [
+ "relations",
+ ],
+ "type": "object",
+ },
+ "name": "create_many_relation_fields",
+ },
+ {
+ "description": "List the validation rules of an object: conditions a record must meet to be saved.",
+ "inputSchema": {
+ "properties": {
+ "objectName": {
+ "description": "Object name, singular or plural (e.g. "company" or "companies").",
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectName",
+ ],
+ "type": "object",
+ },
+ "name": "get_validation_rules",
+ },
+ {
+ "description": "Check a validation rule expression against an object without saving anything. An invalid expression is rejected with the reason.",
+ "inputSchema": {
+ "properties": {
+ "expression": {
+ "description": "Condition that must be true for a record to be saved. When it is false, the write is rejected and the message is shown. Reference fields by name, as returned by get_field_metadata. Use dot access for a composite field part (amount.amountMicros, name.firstName) and for a field of a many-to-one related record (company.name), never brackets. Compare select and multi-select fields with option values, e.g. stage == 'CUSTOMER'. Currency amounts are in micros: amount.amountMicros > 1000000000 means more than 1000. Write text in single quotes. Operators: == != < <= > >= + - * / and or not, and value in [a, b]. now is the date and time of the write; true and false are booleans. Functions: isDefined(value) is true when the value is set, even to an empty text; isEmpty(value) is true when the value is not set, an empty text, an empty list, or a composite field with every part empty; isNonEmptyString(value); includes(listOrText, value) is true when a multi-select or array contains the value, or a text contains a text, case-sensitive; arrayLength(list). To require a field, use not isEmpty(field).",
+ "type": "string",
+ },
+ "objectName": {
+ "description": "Object name, singular or plural (e.g. "company" or "companies").",
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectName",
+ "expression",
+ ],
+ "type": "object",
+ },
+ "name": "validate_validation_rule_expression",
+ },
+ {
+ "description": "Create a validation rule on an object. An invalid expression is rejected with the reason. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), they mean that rule: update it with update_validation_rule instead of creating another one.",
+ "inputSchema": {
+ "properties": {
+ "errorFieldMetadataId": {
+ "description": "ID of the field the message is shown on. Omit to show it on the whole record.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "expression": {
+ "description": "Condition that must be true for a record to be saved. When it is false, the write is rejected and the message is shown. Reference fields by name, as returned by get_field_metadata. Use dot access for a composite field part (amount.amountMicros, name.firstName) and for a field of a many-to-one related record (company.name), never brackets. Compare select and multi-select fields with option values, e.g. stage == 'CUSTOMER'. Currency amounts are in micros: amount.amountMicros > 1000000000 means more than 1000. Write text in single quotes. Operators: == != < <= > >= + - * / and or not, and value in [a, b]. now is the date and time of the write; true and false are booleans. Functions: isDefined(value) is true when the value is set, even to an empty text; isEmpty(value) is true when the value is not set, an empty text, an empty list, or a composite field with every part empty; isNonEmptyString(value); includes(listOrText, value) is true when a multi-select or array contains the value, or a text contains a text, case-sensitive; arrayLength(list). To require a field, use not isEmpty(field).",
+ "type": "string",
+ },
+ "message": {
+ "description": "Message shown to the person saving the record when the expression is false.",
+ "type": "string",
+ },
+ "name": {
+ "description": "Short rule name",
+ "type": "string",
+ },
+ "objectName": {
+ "description": "Object name, singular or plural (e.g. "company" or "companies").",
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectName",
+ "name",
+ "expression",
+ "message",
+ ],
+ "type": "object",
+ },
+ "name": "create_validation_rule",
+ },
+ {
+ "description": "Update a validation rule. Only the provided properties change. When the user is on a validation rule page (a settings path ending in /validation-rules/<id>), requests about a rule are about that one. An active rule rejects an invalid expression with the reason; an inactive rule only checks it when activated, so check it first with validate_validation_rule_expression. Keep the rule inactive unless the user asks to activate it.",
+ "inputSchema": {
+ "properties": {
+ "errorFieldMetadataId": {
+ "anyOf": [
+ {
+ "format": "uuid",
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "ID of the field the message is shown on, or null to show it on the whole record.",
+ },
+ "expression": {
+ "description": "Condition that must be true for a record to be saved. When it is false, the write is rejected and the message is shown. Reference fields by name, as returned by get_field_metadata. Use dot access for a composite field part (amount.amountMicros, name.firstName) and for a field of a many-to-one related record (company.name), never brackets. Compare select and multi-select fields with option values, e.g. stage == 'CUSTOMER'. Currency amounts are in micros: amount.amountMicros > 1000000000 means more than 1000. Write text in single quotes. Operators: == != < <= > >= + - * / and or not, and value in [a, b]. now is the date and time of the write; true and false are booleans. Functions: isDefined(value) is true when the value is set, even to an empty text; isEmpty(value) is true when the value is not set, an empty text, an empty list, or a composite field with every part empty; isNonEmptyString(value); includes(listOrText, value) is true when a multi-select or array contains the value, or a text contains a text, case-sensitive; arrayLength(list). To require a field, use not isEmpty(field).",
+ "type": "string",
+ },
+ "id": {
+ "description": "Validation rule ID",
+ "format": "uuid",
+ "type": "string",
+ },
+ "isActive": {
+ "description": "Set false to turn the rule off without deleting it.",
+ "type": "boolean",
+ },
+ "message": {
+ "description": "Message shown to the person saving the record when the expression is false.",
+ "type": "string",
+ },
+ "name": {
+ "description": "Short rule name",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "update_validation_rule",
+ },
+]
+`;
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts
new file mode 100644
index 00000000000..fbcf9e9d291
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-metadata-tools.integration-spec.ts
@@ -0,0 +1,632 @@
+import { callMcpTool } from 'test/integration/graphql/suites/application-role-intersection/utils/call-mcp-tool.util';
+import { getMcpToolCatalog } from 'test/integration/graphql/suites/application-role-intersection/utils/get-mcp-tool-catalog.util';
+import { deleteOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/delete-one-object-metadata.util';
+import { findManyObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/find-many-object-metadata.util';
+import { updateOneObjectMetadata } from 'test/integration/metadata/suites/object-metadata/utils/update-one-object-metadata.util';
+import { updateFeatureFlag } from 'test/integration/metadata/suites/utils/update-feature-flag.util';
+import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
+import { ToolCategory } from 'twenty-shared/ai';
+import { FeatureFlagKey } from 'twenty-shared/types';
+
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+
+const OBJECT_AND_FIELD_TOOL_NAMES = [
+ 'get_object_metadata',
+ 'create_object_metadata',
+ 'update_object_metadata',
+ 'delete_object_metadata',
+ 'create_many_object_metadata',
+ 'update_many_object_metadata',
+ 'get_field_metadata',
+ 'create_field_metadata',
+ 'update_field_metadata',
+ 'delete_field_metadata',
+ 'create_many_field_metadata',
+ 'update_many_field_metadata',
+ 'create_many_relation_fields',
+];
+
+const VALIDATION_RULE_TOOL_NAMES = [
+ 'get_validation_rules',
+ 'validate_validation_rule_expression',
+ 'create_validation_rule',
+ 'update_validation_rule',
+];
+
+const METADATA_TOOL_NAMES = [
+ ...OBJECT_AND_FIELD_TOOL_NAMES,
+ ...VALIDATION_RULE_TOOL_NAMES,
+];
+
+const OBJECT_NAME_PREFIX = 'mcpMetadataTools';
+const PET_NAME_SINGULAR = `${OBJECT_NAME_PREFIX}Pet`;
+const PET_NAME_PLURAL = `${OBJECT_NAME_PREFIX}Pets`;
+const VISIT_NAME_SINGULAR = `${OBJECT_NAME_PREFIX}Visit`;
+const VISIT_NAME_PLURAL = `${OBJECT_NAME_PREFIX}Visits`;
+const PETS_ON_COMPANY_FIELD_NAME = 'mcpMetadataToolsPets';
+
+type FieldSummary = { id: string; name: string; type: string; label?: string };
+type ObjectSummary = {
+ id: string;
+ nameSingular: string;
+ namePlural: string;
+ fields?: FieldSummary[];
+};
+type ValidationRuleSummary = { id: string; name: string };
+
+const callMetadataTool = ({
+ toolName,
+ toolArguments,
+ token = API_KEY_ACCESS_TOKEN,
+}: {
+ toolName: string;
+ toolArguments: Record<string, unknown>;
+ token?: string;
+}) =>
+ callMcpTool({
+ toolName: 'execute_tool',
+ toolArguments: { toolName, arguments: toolArguments },
+ token,
+ });
+
+const runMetadataTool = async <TResult>(
+ call: Parameters<typeof callMetadataTool>[0],
+): Promise<TResult | undefined> => {
+ const result = await callMetadataTool(call);
+
+ expect(result.isError).toBe(false);
+
+ const output: ToolOutput<TResult> = JSON.parse(result.content[0].text);
+
+ expect(output.success).toBe(true);
+
+ return output.result;
+};
+
+const runFailingMetadataTool = async (
+ call: Parameters<typeof callMetadataTool>[0],
+): Promise<ToolOutput> => {
+ const result = await callMetadataTool(call);
+
+ expect(result.isError).toBe(true);
+
+ return JSON.parse(result.content[0].text);
+};
+
+const listObjects = async (
+ toolArguments: Record<string, unknown>,
+): Promise<ObjectSummary[]> => {
+ const result = await runMetadataTool<{ objects: ObjectSummary[] }>({
+ toolName: 'get_object_metadata',
+ toolArguments,
+ });
+
+ jestExpectToBeDefined(result);
+
+ return result.objects;
+};
+
+const listFields = async (
+ toolArguments: Record<string, unknown>,
+): Promise<FieldSummary[]> => {
+ const result = await runMetadataTool<{ fields: FieldSummary[] }>({
+ toolName: 'get_field_metadata',
+ toolArguments,
+ });
+
+ jestExpectToBeDefined(result);
+
+ return result.fields;
+};
+
+const findObjectOrThrow = async (objectName: string) => {
+ const [object] = await listObjects({ objectName });
+
+ jestExpectToBeDefined(object);
+
+ return object;
+};
+
+const findFieldOrThrow = async ({
+ objectName,
+ fieldName,
+}: {
+ objectName: string;
+ fieldName: string;
+}) => {
+ const field = (await listFields({ objectName })).find(
+ ({ name }) => name === fieldName,
+ );
+
+ jestExpectToBeDefined(field);
+
+ return field;
+};
+
+describe('MCP metadata tools (integration)', () => {
+ afterAll(async () => {
+ const { objects } = await findManyObjectMetadata({
+ expectToFail: false,
+ input: { filter: {}, paging: { first: 1000 } },
+ gqlFields: 'id nameSingular',
+ });
+
+ for (const { id, nameSingular } of objects ?? []) {
+ if (!nameSingular.startsWith(OBJECT_NAME_PREFIX)) {
+ continue;
+ }
+
+ await updateOneObjectMetadata({
+ expectToFail: false,
+ input: { idToUpdate: id, updatePayload: { isActive: false } },
+ });
+ await deleteOneObjectMetadata({
+ expectToFail: false,
+ input: { idToDelete: id },
+ });
+ }
+ });
+
+ it('should describe the metadata tools to the model', async () => {
+ const result = await callMcpTool({
+ toolName: 'learn_tools',
+ toolArguments: { toolNames: METADATA_TOOL_NAMES },
+ token: API_KEY_ACCESS_TOKEN,
+ });
+
+ expect(result.isError).toBe(false);
+
+ const payload = JSON.parse(result.content[0].text);
+
+ expect(payload.notFound).toEqual([]);
+ expect(payload.tools).toMatchSnapshot();
+ });
+
+ it('should list the metadata tools in the metadata category', async () => {
+ const catalog = await getMcpToolCatalog({ token: API_KEY_ACCESS_TOKEN });
+
+ expect(catalog[ToolCategory.METADATA].map(({ name }) => name)).toEqual(
+ METADATA_TOOL_NAMES,
+ );
+ });
+
+ it('should build, edit and delete a custom object', async () => {
+ const createdPet = await runMetadataTool<ObjectSummary>({
+ toolName: 'create_object_metadata',
+ toolArguments: {
+ nameSingular: PET_NAME_SINGULAR,
+ namePlural: PET_NAME_PLURAL,
+ labelSingular: 'MCP metadata tools pet',
+ labelPlural: 'MCP metadata tools pets',
+ icon: 'paw',
+ },
+ });
+
+ expect(createdPet).toEqual({
+ id: expect.any(String),
+ nameSingular: PET_NAME_SINGULAR,
+ labelSingular: 'MCP metadata tools pet',
+ });
+
+ const petId = createdPet?.id;
+
+ jestExpectToBeDefined(petId);
+
+ expect(
+ await listObjects({ objectName: PET_NAME_PLURAL, includeFields: true }),
+ ).toEqual([
+ expect.objectContaining({
+ id: petId,
+ nameSingular: PET_NAME_SINGULAR,
+ namePlural: PET_NAME_PLURAL,
+ labelPlural: 'MCP metadata tools pets',
+ icon: 'IconPaw',
+ fields: expect.arrayContaining([
+ { id: expect.any(String), name: 'name', type: 'TEXT', label: 'Name' },
+ ]),
+ }),
+ ]);
+
+ expect(
+ await runMetadataTool({
+ toolName: 'update_object_metadata',
+ toolArguments: {
+ id: petId,
+ labelSingular: 'MCP metadata tools animal',
+ description: 'Animals followed by the clinic',
+ },
+ }),
+ ).toEqual({
+ id: petId,
+ nameSingular: PET_NAME_SINGULAR,
+ labelSingular: 'MCP metadata tools animal',
+ });
+
+ const nicknameField = await runMetadataTool<FieldSummary>({
+ toolName: 'create_field_metadata',
+ toolArguments: {
+ objectMetadataId: petId,
+ type: 'TEXT',
+ name: 'nickname',
+ label: 'Nickname',
+ },
+ });
+
+ jestExpectToBeDefined(nicknameField);
+ expect(nicknameField).toEqual({
+ id: expect.any(String),
+ name: 'nickname',
+ label: 'Nickname',
+ type: 'TEXT',
+ objectMetadataId: petId,
+ });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'update_field_metadata',
+ toolArguments: { id: nicknameField.id, label: 'Pet nickname' },
+ }),
+ ).toEqual({
+ id: nicknameField.id,
+ name: 'nickname',
+ label: 'Pet nickname',
+ type: 'TEXT',
+ });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'create_many_field_metadata',
+ toolArguments: {
+ fields: [
+ {
+ objectMetadataId: petId,
+ type: 'NUMBER',
+ name: 'age',
+ label: 'Age',
+ },
+ {
+ objectMetadataId: petId,
+ type: 'SELECT',
+ name: 'species',
+ label: 'Species',
+ options: [
+ { label: 'Dog', value: 'DOG', position: 0, color: 'blue' },
+ { label: 'Cat', value: 'CAT', position: 1, color: 'green' },
+ ],
+ },
+ ],
+ },
+ }),
+ ).toBeUndefined();
+
+ const ageField = await findFieldOrThrow({
+ objectName: PET_NAME_SINGULAR,
+ fieldName: 'age',
+ });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'update_many_field_metadata',
+ toolArguments: {
+ fields: [{ id: ageField.id, label: 'Age in years' }],
+ },
+ }),
+ ).toBeUndefined();
+
+ const petFields = await listFields({ objectMetadataId: petId });
+
+ expect(petFields).toEqual(
+ expect.arrayContaining([
+ { id: expect.any(String), name: 'id', type: 'UUID' },
+ expect.objectContaining({
+ id: ageField.id,
+ name: 'age',
+ type: 'NUMBER',
+ label: 'Age in years',
+ }),
+ expect.objectContaining({
+ name: 'species',
+ type: 'SELECT',
+ label: 'Species',
+ }),
+ expect.objectContaining({
+ id: nicknameField.id,
+ name: 'nickname',
+ label: 'Pet nickname',
+ }),
+ ]),
+ );
+ expect(petFields.map(({ name }) => name)).not.toContain('position');
+
+ const company = await findObjectOrThrow('company');
+
+ expect(
+ await runMetadataTool({
+ toolName: 'create_many_relation_fields',
+ toolArguments: {
+ relations: [
+ {
+ objectMetadataId: petId,
+ name: 'company',
+ label: 'Company',
+ type: 'MANY_TO_ONE',
+ targetObjectMetadataId: company.id,
+ targetFieldLabel: 'MCP metadata tools pets',
+ targetFieldIcon: 'IconPaw',
+ },
+ ],
+ },
+ }),
+ ).toBeUndefined();
+
+ expect(
+ await findFieldOrThrow({
+ objectName: PET_NAME_SINGULAR,
+ fieldName: 'company',
+ }),
+ ).toMatchObject({ type: 'RELATION', label: 'Company' });
+ expect(
+ await findFieldOrThrow({
+ objectName: 'company',
+ fieldName: PETS_ON_COMPANY_FIELD_NAME,
+ }),
+ ).toMatchObject({ type: 'RELATION', label: 'MCP metadata tools pets' });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'create_many_object_metadata',
+ toolArguments: {
+ objects: [
+ {
+ nameSingular: VISIT_NAME_SINGULAR,
+ namePlural: VISIT_NAME_PLURAL,
+ labelSingular: 'MCP metadata tools visit',
+ labelPlural: 'MCP metadata tools visits',
+ icon: 'IconStethoscope',
+ },
+ ],
+ },
+ }),
+ ).toBeUndefined();
+
+ const visit = await findObjectOrThrow(VISIT_NAME_SINGULAR);
+
+ expect(
+ await runMetadataTool({
+ toolName: 'update_many_object_metadata',
+ toolArguments: {
+ objects: [{ id: visit.id, description: 'Visits to the clinic' }],
+ },
+ }),
+ ).toBeUndefined();
+ expect(await findObjectOrThrow(VISIT_NAME_SINGULAR)).toMatchObject({
+ description: 'Visits to the clinic',
+ });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'create_field_metadata',
+ toolArguments: {
+ objectMetadataId: visit.id,
+ type: 'RELATION',
+ name: 'pet',
+ label: 'Pet',
+ relationCreationPayload: {
+ type: 'MANY_TO_ONE',
+ targetObjectMetadataId: petId,
+ targetFieldLabel: 'Visits',
+ },
+ },
+ }),
+ ).toMatchObject({
+ name: 'pet',
+ type: 'RELATION',
+ objectMetadataId: visit.id,
+ });
+ expect(
+ await findFieldOrThrow({
+ objectName: PET_NAME_SINGULAR,
+ fieldName: 'visits',
+ }),
+ ).toMatchObject({ type: 'RELATION', label: 'Visits' });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'get_validation_rules',
+ toolArguments: { objectName: PET_NAME_SINGULAR },
+ }),
+ ).toEqual([]);
+
+ expect(
+ await runMetadataTool({
+ toolName: 'validate_validation_rule_expression',
+ toolArguments: {
+ objectName: PET_NAME_SINGULAR,
+ expression: 'age >= 0',
+ },
+ }),
+ ).toBeUndefined();
+
+ const validationRule = await runMetadataTool<ValidationRuleSummary>({
+ toolName: 'create_validation_rule',
+ toolArguments: {
+ objectName: PET_NAME_PLURAL,
+ name: 'Non-negative age',
+ expression: 'age >= 0',
+ message: 'Age cannot be negative',
+ errorFieldMetadataId: ageField.id,
+ },
+ });
+
+ jestExpectToBeDefined(validationRule);
+ expect(validationRule).toMatchObject({
+ name: 'Non-negative age',
+ expression: 'age >= 0',
+ message: 'Age cannot be negative',
+ errorFieldMetadataId: ageField.id,
+ objectMetadataId: petId,
+ });
+
+ expect(
+ await runMetadataTool({
+ toolName: 'update_validation_rule',
+ toolArguments: {
+ id: validationRule.id,
+ message: 'An age cannot be negative',
+ isActive: false,
+ },
+ }),
+ ).toMatchObject({
+ id: validationRule.id,
+ message: 'An age cannot be negative',
+ isActive: false,
+ });
+
+ expect(
+ await runMetadataTool<ValidationRuleSummary[]>({
+ toolName: 'get_validation_rules',
+ toolArguments: { objectName: PET_NAME_SINGULAR },
+ }),
+ ).toEqual([expect.objectContaining({ id: validationRule.id })]);
+
+ expect(
+ await runMetadataTool({
+ toolName: 'delete_field_metadata',
+ toolArguments: { id: nicknameField.id },
+ }),
+ ).toEqual({ id: nicknameField.id, deleted: true });
+ expect(
+ (await listFields({ objectMetadataId: petId })).map(({ id }) => id),
+ ).not.toContain(nicknameField.id);
+
+ for (const objectId of [visit.id, petId]) {
+ expect(
+ await runMetadataTool({
+ toolName: 'delete_object_metadata',
+ toolArguments: { id: objectId },
+ }),
+ ).toEqual({ id: objectId, deleted: true });
+ }
+
+ expect(await listObjects({ objectName: PET_NAME_SINGULAR })).toEqual([]);
+ expect(
+ (await listFields({ objectMetadataId: company.id })).map(
+ ({ name }) => name,
+ ),
+ ).not.toContain(PETS_ON_COMPANY_FIELD_NAME);
+ });
+
+ it.each([
+ {
+ toolName: 'get_field_metadata',
+ toolArguments: { objectName: 'unknownObject' },
+ },
+ {
+ toolName: 'get_validation_rules',
+ toolArguments: { objectName: 'unknownObject' },
+ },
+ {
+ toolName: 'create_validation_rule',
+ toolArguments: {
+ objectName: 'unknownObject',
+ name: 'Rule',
+ expression: 'true',
+ message: 'Message',
+ },
+ },
+ ])(
+ 'should refuse $toolName on an unknown object name',
+ async ({ toolName, toolArguments }) => {
+ expect(await runFailingMetadataTool({ toolName, toolArguments })).toEqual(
+ {
+ success: false,
+ message: `Failed to execute ${toolName}`,
+ error:
+ 'Object "unknownObject" not found. Use get_object_metadata to list available objects.',
+ },
+ );
+ },
+ );
+
+ it('should refuse an expression on an unknown field', async () => {
+ expect(
+ await runFailingMetadataTool({
+ toolName: 'validate_validation_rule_expression',
+ toolArguments: {
+ objectName: 'company',
+ expression: 'unknownField > 1',
+ },
+ }),
+ ).toMatchObject({
+ success: false,
+ message: 'Failed to execute validate_validation_rule_expression',
+ });
+ });
+
+ // The seeded member and guest roles cannot update settings, so they lack DATA_MODEL
+ describe.each([
+ { caller: 'a member', token: APPLE_JONY_MEMBER_ACCESS_TOKEN },
+ { caller: 'a guest', token: APPLE_PHIL_GUEST_ACCESS_TOKEN },
+ ])('for $caller without DATA_MODEL', ({ token }) => {
+ it('should not list the metadata category', async () => {
+ const catalog = await getMcpToolCatalog({ token });
+
+ expect(catalog[ToolCategory.METADATA]).toBeUndefined();
+ expect(Object.keys(catalog)).not.toHaveLength(0);
+ });
+
+ it.each(METADATA_TOOL_NAMES)('should refuse %s', async (toolName) => {
+ expect(
+ await runFailingMetadataTool({ toolName, toolArguments: {}, token }),
+ ).toMatchObject({
+ success: false,
+ message: `Tool "${toolName}" not found`,
+ });
+ });
+ });
+
+ describe('with IS_RECORD_CREATION_FORM_ENABLED off', () => {
+ beforeAll(async () => {
+ await updateFeatureFlag({
+ featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
+ value: false,
+ expectToFail: false,
+ });
+ });
+
+ // The flag is seeded on
+ afterAll(async () => {
+ await updateFeatureFlag({
+ featureFlag: FeatureFlagKey.IS_RECORD_CREATION_FORM_ENABLED,
+ value: true,
+ expectToFail: false,
+ });
+ });
+
+ it('should list the object and field tools only', async () => {
+ const catalog = await getMcpToolCatalog({ token: API_KEY_ACCESS_TOKEN });
+
+ expect(catalog[ToolCategory.METADATA].map(({ name }) => name)).toEqual(
+ OBJECT_AND_FIELD_TOOL_NAMES,
+ );
+ });
+
+ it('should still run an object tool', async () => {
+ expect(await findObjectOrThrow('company')).toMatchObject({
+ nameSingular: 'company',
+ });
+ });
+
+ it.each(VALIDATION_RULE_TOOL_NAMES)(
+ 'should refuse %s',
+ async (toolName) => {
+ expect(
+ await runFailingMetadataTool({ toolName, toolArguments: {} }),
+ ).toMatchObject({
+ success: false,
+ message: `Tool "${toolName}" not found`,
+ });
+ },
+ );
+ });
+});