OrgGen AI

add_entity_with_fields

Destructive

⚡ Creates the entity AND all its fields in a single call — divides the number of round trips by 5–10 compared with add_entity + N×add_field, for an ERD of 6 tables × 5 columns when the fields are known at creation. FKs (type=reference) are only allowed if the target entity already exists: entities without FKs are born first, the FKs are then added via add_fields_batch once all the tables exist.

Input Schema

Name	Required	Description
`x`	No	X position in pixels. x/y omitted (recommended): automatic placement, then auto_layout_mcd for the final tidy-up.
`y`	No	Y position in pixels. See x — leaving it absent = automatic placement.
`id`	Yes	Unique kebab-case ID of the entity (e.g. 'users')
`desc`	No
`name`	Yes	Display name of the entity
`width`	No
`fields`	Yes	List of the fields to create at the same time as the entity. The order of the array defines the display order. FKs (type=reference) are only allowed if the target entity already exists — otherwise, entities are created first without FKs, then the FKs are added via add_fields_batch.
`height`	No
`colorKey`	No
`parentId`	No
`kindMetadata`	No	Postgres metadata of the table: schemaNamespace (chip 'auth.users'), rlsPolicy (chip 🔒 + DDL export), piiFields (GDPR), expectedRowCount. REPLACES the existing block; {} clears everything, an omitted field is not touched.
`expectedProjectId`	No	UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted.

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedOct 21, 2026

changedInput schema / properties / expectedProjectId / description

Previous value: -"UUID du projet visé par CET appel. Cible RÉELLEMENT ce projet au lieu du projet de session. Refusé sans rien modifier si l'accès n'est pas accordé."New value: +"UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted."

changedInput schema / properties / fields / description

Previous value: -"Liste des champs à créer en même temps que l'entité. L'ordre du tableau définit l'ordre d'affichage. Les FK (type=reference) ne sont autorisées que si l'entité cible existe déjà — sinon, les entités se créent d'abord sans FK, puis les FK s'ajoutent via add_fields_batch."New value: +"List of the fields to create at the same time as the entity. The order of the array defines the display order. FKs (type=reference) are only allowed if the target entity already exists — otherwise, entities are created first without FKs, then the FKs are added via add_fields_batch."

changedInput schema / properties / fields / items / properties / id / description

Previous value: -"ID unique du champ (ex: 'users-email')"New value: +"Unique ID of the field (e.g. 'users-email')"

changedInput schema / properties / fields / items / properties / name / description
```
Previous value: -"Nom du champ"New value: +"Name of the field"
```

changedInput schema / properties / fields / items / properties / type / description

Previous value: -"Type discriminé par kind"New value: +"Type discriminated by kind"

changedInput schema / properties / fields / items / properties / type / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "string",
-        "type": "string"
-      },
-      "length": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "text",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "int",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "bigint",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "float",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "boolean",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "uuid",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "date",
-        "type": "string"
-      },
-      "withTimezone": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "timestamp",
-        "type": "string"
-      },
-      "withTimezone": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "jsonb",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "enum",
-        "type": "string"
-      },
-      "values": {
-        "description": "La liste COMPLÈTE des valeurs de l'énumération — elle REMPLACE celle qui est stockée. Pour en ajouter une, toutes les valeurs existantes (lisibles sur le champ) se renvoient avec la nouvelle.",
-        "items": {
-          "minLength": 1,
-          "type": "string"
-        },
-        "minItems": 1,
-        "type": "array"
-      }
-    },
-    "required": [
-      "kind",
-      "values"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "reference",
-        "type": "string"
-      },
-      "referencesCellId": {
-        "minLength": 1,
-        "type": "string"
-      },
-      "referencesFieldId": {
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "referencesCellId",
-      "referencesFieldId"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "string",
+        "type": "string"
+      },
+      "length": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "text",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "int",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "bigint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "float",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "boolean",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "uuid",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "date",
+        "type": "string"
+      },
+      "withTimezone": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "timestamp",
+        "type": "string"
+      },
+      "withTimezone": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "jsonb",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "enum",
+        "type": "string"
+      },
+      "values": {
+        "description": "The COMPLETE list of the enumeration's values — it REPLACES the stored one. To add one, all the existing values (readable on the field) are sent back along with the new one.",
+        "items": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "kind",
+      "values"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "reference",
+        "type": "string"
+      },
+      "referencesCellId": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "referencesFieldId": {
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "referencesCellId",
+      "referencesFieldId"
+    ],
+    "type": "object"
+  }
+]

changedInput schema / properties / id / description

Previous value: -"ID unique kebab-case de l'entité (ex: 'users')"New value: +"Unique kebab-case ID of the entity (e.g. 'users')"

changedInput schema / properties / kindMetadata / description

Previous value: -"Métadonnées Postgres de la table : schemaNamespace (chip 'auth.users'), rlsPolicy (chip 🔒 + export DDL), piiFields (RGPD), expectedRowCount. REMPLACE le bloc existant ; {} efface tout, un champ omis n'est pas touché."New value: +"Postgres metadata of the table: schemaNamespace (chip 'auth.users'), rlsPolicy (chip 🔒 + DDL export), piiFields (GDPR), expectedRowCount. REPLACES the existing block; {} clears everything, an omitted field is not touched."

changedInput schema / properties / kindMetadata / properties / piiFields / description

Previous value: -"Champs porteurs de données personnelles — point rouge RGPD sur la rangée + tooltip."New value: +"Fields carrying personal data — red GDPR dot on the row + tooltip."

changedInput schema / properties / kindMetadata / properties / piiFields / items / properties / fieldId / description

Previous value: -"ID du champ concerné (celui passé à add_field)"New value: +"ID of the field concerned (the one passed to add_field)"

changedInput schema / properties / kindMetadata / properties / piiFields / items / properties / piiClass / description
```
Previous value: -"Nature de la donnée personnelle"New value: +"Nature of the personal data"
```

changedInput schema / properties / name / description

Previous value: -"Nom affiché de l'entité"New value: +"Display name of the entity"

changedInput schema / properties / x / description

Previous value: -"Position X en pixels. x/y omis (recommandé) : placement automatique, puis auto_layout_mcd pour la mise au propre finale."New value: +"X position in pixels. x/y omitted (recommended): automatic placement, then auto_layout_mcd for the final tidy-up."

changedInput schema / properties / y / description

Previous value: -"Position Y en pixels. Voir x — laisser absent = placement auto."New value: +"Y position in pixels. See x — leaving it absent = automatic placement."

Changed4 schema fields changedOct 20, 2026

changedInput schema / properties / fields / description

Previous value: -"Liste des champs à créer en même temps que l'entité. L'ordre du tableau définit l'ordre d'affichage. Les FK (type=reference) ne sont autorisées que si l'entité cible existe déjà — sinon, créer d'abord les entités sans FK, puis ajouter les FK via add_fields_batch."New value: +"Liste des champs à créer en même temps que l'entité. L'ordre du tableau définit l'ordre d'affichage. Les FK (type=reference) ne sont autorisées que si l'entité cible existe déjà — sinon, les entités se créent d'abord sans FK, puis les FK s'ajoutent via add_fields_batch."

changedInput schema / properties / fields / items / properties / type / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "string",
-        "type": "string"
-      },
-      "length": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "text",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "int",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "bigint",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "float",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "boolean",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "uuid",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "date",
-        "type": "string"
-      },
-      "withTimezone": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "timestamp",
-        "type": "string"
-      },
-      "withTimezone": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "jsonb",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "enum",
-        "type": "string"
-      },
-      "values": {
-        "description": "La liste COMPLÈTE des valeurs de l'énumération — elle REMPLACE celle qui est stockée. Pour en ajouter une, relis le champ et renvoie toutes les valeurs existantes avec la nouvelle.",
-        "items": {
-          "minLength": 1,
-          "type": "string"
-        },
-        "minItems": 1,
-        "type": "array"
-      }
-    },
-    "required": [
-      "kind",
-      "values"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "reference",
-        "type": "string"
-      },
-      "referencesCellId": {
-        "minLength": 1,
-        "type": "string"
-      },
-      "referencesFieldId": {
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "referencesCellId",
-      "referencesFieldId"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "string",
+        "type": "string"
+      },
+      "length": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "text",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "int",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "bigint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "float",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "boolean",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "uuid",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "date",
+        "type": "string"
+      },
+      "withTimezone": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "timestamp",
+        "type": "string"
+      },
+      "withTimezone": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "jsonb",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "enum",
+        "type": "string"
+      },
+      "values": {
+        "description": "La liste COMPLÈTE des valeurs de l'énumération — elle REMPLACE celle qui est stockée. Pour en ajouter une, toutes les valeurs existantes (lisibles sur le champ) se renvoient avec la nouvelle.",
+        "items": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "kind",
+      "values"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "reference",
+        "type": "string"
+      },
+      "referencesCellId": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "referencesFieldId": {
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "referencesCellId",
+      "referencesFieldId"
+    ],
+    "type": "object"
+  }
+]

changedInput schema / properties / kindMetadata / description

Previous value: -"Métadonnées Postgres de la table : schemaNamespace (chip 'auth.users'), rlsPolicy (chip 🔒 + export DDL), piiFields (RGPD), expectedRowCount. REMPLACE le bloc existant ; {} efface tout, omettre le champ ne touche à rien."New value: +"Métadonnées Postgres de la table : schemaNamespace (chip 'auth.users'), rlsPolicy (chip 🔒 + export DDL), piiFields (RGPD), expectedRowCount. REMPLACE le bloc existant ; {} efface tout, un champ omis n'est pas touché."

changedInput schema / properties / x / description

Previous value: -"Position X en pixels. OMETS x/y (recommandé) : placement automatique, puis auto_layout_mcd pour la mise au propre finale."New value: +"Position X en pixels. x/y omis (recommandé) : placement automatique, puis auto_layout_mcd pour la mise au propre finale."

First observedOct 20, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is known; the description adds the genuinely non-obvious ordering constraint on reference fields and the round-trip cost tradeoff. It does not cover failure behavior (duplicate `id`, atomicity/partial-creation on error), which is the remaining gap for a destructive write.

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

Conciseness4/5

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

Two dense sentences, front-loaded with the value proposition before the FK caveat; nothing is filler. The ⚡ glyph and the parenthetical round-trip arithmetic are marginal, but they support the speed argument rather than distract from it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter nested, destructive creation tool with no output schema, the description covers the decision-relevant risk (FK ordering, batching alternative) while the schema carries most field-level detail. It could say more about what is returned or what happens when `id` already exists, but nothing required to call it correctly is missing.

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

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is ~58%, with parameters like `width`, `height`, `colorKey`, `parentId` and `desc` undocumented in both places. The description adds meaning only for `fields` — array order defines display order and FK entries require an existing target — which is valuable but leaves the geometry/parenting parameters unexplained. Baseline 3 fits given the partial schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (creates the entity AND all its fields in one call) and explicitly contrasts it with the `add_entity` + N×`add_field` path, so an agent can distinguish it from those siblings without opening any schema. The concrete '6 tables × 5 columns' framing pins down the intended shape of the call.

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

Usage Guidelines5/5

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

Gives the selection condition ('when the fields are known at creation') against the named alternatives, and handles the main edge case: FKs are only allowed if the target entity exists, so create FK-free entities first and add the references afterwards via `add_fields_batch`. That is both a when-to-use and a when-not-to-use rule.

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

All OrgGen AI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

add_entity_with_fields

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources