Designing an agent-friendly schema
Shape your objects, fields, types and permissions so an AI agent can discover and safely operate them through MCP.
When an agent works through MCP it only ever sees what the engine tells it: the objects from
list_objects and one object's shape from describe_object. The quality of that metadata is the
ceiling on what the agent can do safely — a vague field name or an over-broad permission reads to the
model as an invitation to guess.
This practice is the schema-side companion to Exposing a large schema to an agent: that page is about how the agent discovers and acts; this one is about making what it discovers worth acting on.
Why it matters
The agent never reads your TypeScript or your migration history. It reads describe_object, which
surfaces field names, labels, descriptions, types, relations, enum options, and your effective
permissions — already filtered by RBAC. Everything you intend the agent to understand has to be in
that description. Treat it as the API documentation your most literal consumer will ever read.
Names and labels
- Name in
snake_case, and declare a primary key. Names are the agent's vocabulary;shipped_atbeatsshipdate. A single scalarprimarycolumn is simplest — a string column (a UUID or a human-readable code likedoc_no) keeps relation arguments simple; composite keys (severalprimary: truefields) are supported too. - Add
labelsfor display, keepnamefor identity.labels(per locale) give the agent a human phrase to show ("Order"), whilenamestays the stable machine handle. - Write a
descriptionon every field the agent must not misread. A one-linedescriptionis the difference between the agent writingstatus: "shipped"and inventingstatus: "sent".
// objects/orders/schema.json
{
"name": "orders",
"labels": { "en": "Order" },
"fields": [
{ "name": "id", "type": "string", "primary": true, "description": "Order code, e.g. O-1001" },
{ "name": "customer_id", "type": "relation", "target": "customers", "required": true },
{
"name": "status",
"type": "enum",
"options": ["pending", "paid", "cancelled"],
"description": "Lifecycle state; only pending → paid/cancelled is valid"
},
{ "name": "amount", "type": "currency" },
{ "name": "created_at", "type": "timestamptz" }
]
}Self-documenting types
Field types carry meaning the agent can use — prefer the most specific type that fits:
enumover freestringfor any closed set. The options appear indescribe_object, so the agent picks a valid value instead of guessing.- Semantic types over raw primitives —
email,phone,image,user,department,firstName/lastName. They inherit storage from a primitive but tell the agent (and the frontend) what the value is. - Business semantics via custom field types — when a domain concept recurs (
money,rating,address), register a namespaced type over a base primitive instead of re-explaining it per field. See Custom field types. - Computed values as formulas, not writable columns —
formulafields are read-only and persisted, so the agent cannot corrupt a derived total. titleTemplategives a record a readable title (e.g."{id} · {status}"), which makes search and get results legible to the model.
Relations
Relations are how the agent navigates the domain, so get the targets and cardinality right:
relation— a reference to another object's primary value (single-key target) or itsrecord_key(composite-key target).details— strong 1:N ownership managed through the child object's own CRUD, not nested writes.multiRelation— a multi-select of references (an engine-managed link table with per-side FKs; reads return the target-id array).
Name relation fields after their target (customer_id, not cust) and mark the required ones; the
agent reads cardinality from the relation list in describe_object.
RBAC an agent can live with
Permissions are part of the description the agent sees, and the real enforcement boundary at call time. Design them so "what the agent sees" and "what it may do" agree:
- Start from the role's job. Give
vieweronly areadscope; give writing roles an explicitupdateallowlist rather thantrue. - Scope reads by rows.
read: "own"(with anownership: truefield) orread: "department"(with adepartmentfield, or derived from the owner) keeps an agent inside one person's data —departmentincludes the subtree, so a manager sees their team's rows. - Hide what must not be read.
fields.exclude: ["secret"]removes the column fromdescribe_object, from search results, and from writes — the agent cannot reference what it cannot see. - Whitelist writes. A non-empty
updatelist (andcreate/fields.create) means the agent can only touch the columns you named; anything else is a denial, not a silent no-op.
"permissions": {
"viewer": { "read": "all", "fields": { "exclude": ["internal_note"] } },
"agent": { "read": "own", "create": true, "update": ["status", "amount"] }
}Narrow high-risk writes with custom tools
Generic CRUD is the floor, not the ceiling. When an operation has business rules an agent should not
re-derive — refunds, credits, reassignments — model it as a custom tool with its own schema, role
allowlist, and guardrail policy (including requireApproval for a human-in-the-loop step). The agent
then calls your named operation instead of composing raw updates. See
Custom tools, guardrails & audit replay and
Approvals.
Anti-patterns
read: "all"on a table with sensitive columns — the agent sees (and can exfiltrate) every field it can read. Exclude first.update: truewhere an allowlist would do — a broad write surface is how an agent "helpfully" edits the wrong column.- Free-form
stringfor closed sets — the agent invents values that fail validation, or worse, writes plausible-but-wrong ones into an unconstrained column. - Undescribed fields with cryptic names —
c_stat,flag2. The agent will guess; document them or exclude them.
Related
- Exposing a large schema to an agent — the fixed registry surface and the discovery workflow this metadata serves.
- Schema guide — fields, relations, computed fields and validation.
- RBAC — roles, permissions and row scopes in full.
- MCP — the adapter contract.