FileMakerAIdatabase annotationschema documentationGetTableDDLsemantic metadata
Why Should Your FileMaker Database Be Annotated So LLMs Can Understand It?

Why Should Your FileMaker Database Be Annotated So LLMs Can Understand It?

Shubham·

LLMs cannot understand your database schema from field names alone. Learn why annotating your FileMaker database — and any business database — with semantic metadata is the critical first step to making AI tools useful, accurate, and safe in your organization.

Why Should Your FileMaker Database Be Annotated So LLMs Can Understand It?

Your company has a FileMaker database. It works. People enter orders, track jobs, manage inventory, and generate invoices. The system has been running for years — maybe a decade. Now your CEO wants to connect an AI assistant to it so the operations team can ask questions like "Which orders are delayed?" or "What's our inventory value by category?" and get answers in seconds.

Here's the problem: an LLM does not understand your database. It has no idea what a field called b_Active means, whether n_Status with a value of "3" refers to "shipped," "pending approval," or something else entirely, or that fk_CustomerID links to a customer record. It sees names, types, and relationships — but not meaning.

The result? Confident-sounding answers that are quietly wrong. An AI assistant that invents SQL joins because it guessed a relationship. A chatbot that returns "Hold" status orders when the user meant "urgent." These are not hypothetical failures. They are the default outcome when you connect LLMs to undocumented schemas.

The solution is annotation: adding plain-English descriptions to your tables and fields so that when an LLM receives your schema, it can understand not just the structure but the business logic behind it. This article explains why annotation matters, how it works in practice, what the latest research says about its impact, and how you can start — whether you use FileMaker 2026, another platform, or a hybrid environment.

What Does "Annotation" Actually Mean?

Annotation is the practice of adding human-readable descriptions to database objects — tables, fields, and relationships — that explain what each element represents, how it should be used, and what its values mean in business terms.

In a FileMaker context, this can take several forms:

  • Field comments: Short text descriptions stored alongside a field definition. FileMaker has supported these for years, and since version 2025 (v22), a special [LLM] tag prefix could signal that a comment was intended for AI consumption.
  • Field annotations (FileMaker 2026+): A dedicated metadata layer introduced in FileMaker 26, stored in the Advanced Options dialog for each field. These are separate from field comments and are specifically designed to be consumed by AI systems via the GetTableDDL function.
  • Table-level annotations: Descriptions of what an entire table represents (e.g., "This table stores all active and historical production jobs, including scheduled and completed work").
  • Relationship metadata: Explanations of how tables connect, especially when the relationship names are cryptic or ambiguous.

Think of it this way: DDL tells the AI what the field is. Annotations tell the AI what the field means.

A field named n_TaxRate with a type of Decimal tells an LLM that it stores a number. An annotation like "Tax rate stored as a decimal fraction (e.g., 0.07 for 7%). Used in invoice line calculations." tells the LLM how to interpret and use that number correctly.

Why LLMs Fail Without Annotation

Large language models are remarkably good at generating SQL, writing scripts, and answering questions about data — but only when they have enough context. Without annotation, an LLM faces several categories of failure:

1. Ambiguous field names

A field called Status might appear in five different tables, each with completely different value sets. Without annotation, an LLM has no way to know that Status = 3 means "Shipped" in the Orders table but "Active" in the Users table.

As Claris notes in its own best practices documentation, adding annotations that clarify disambiguation — like "Status of the order: 1=Pending, 2=Processing, 3=Shipped, 4=Delivered" — directly improves the quality of AI-generated queries.

2. Undocumented business logic

FileMaker fields often carry implicit business rules in their calculation formulas, auto-enter scripts, or value lists. An LLM cannot read the meaning of a calculation formula without understanding the business context. A field whose formula is GetAsDate ( DueDate ) + 30 means "30 days after the due date" — but what does "due date" represent in this context? Annotation answers that question.

3. Hidden constraints and formats

Fields that store percentages as whole numbers (e.g., 7 for 7%), values in cents instead of dollars, or dates in non-standard formats will produce wrong results if an LLM does not know the convention. Annotations like "Stored as whole number percentage (7 = 7%)" prevent entire categories of calculation errors.

4. Read-only and structural fields

Calculation fields, auto-enter serial numbers, and global fields all behave differently from data-entry fields. Without annotation, an LLM may try to write to a read-only field, insert into a summary field, or misunderstand why a field always contains the same value.

5. The "confident but wrong" problem

This is the most dangerous failure mode. An LLM will always produce an answer. If the schema is ambiguous, it will guess — and the guess will be delivered with the same confidence as a correct answer. Users will not know the difference until the damage is done.

What the 2026 Research Says

The importance of database annotation is not just a practitioner's observation — it is now backed by significant academic research.

DBAutoDoc: Iterative schema documentation

A 2026 paper from arXiv introduced DBAutoDoc, a system that automates the discovery and documentation of undocumented relational database schemas. The key finding: treating schema documentation as an iterative learning problem — rather than a one-shot extraction task — produces dramatically better results.

Across a suite of benchmark databases, DBAutoDoc achieved an overall weighted score of 96.1% on a composite metric spanning key discovery accuracy and description coverage, evaluated across two model families (Gemini and Claude). It detected 97% of primary keys in the benchmark set, and an ablation study found that its deterministic statistical pipeline delivers a 23-point F1 improvement over relying on an LLM alone for foreign-key detection. The system converges within 2 iterations on average, at a cost of roughly $0.70 per 100 tables — a reduction of more than 99.5% relative to manual documentation.

The implication for business databases: even if your schema is poorly documented today, the combination of statistical analysis and LLM-based inference can recover much of the structure — but it works far better when human annotations exist as anchor points.

TYTAN: Interactive schema construction

TYTAN, published in August 2026, takes a neurosymbolic approach: it combines symbolic analysis of the database with LLM-based semantic inference for entity proposal, role assignment, and naming. Across seven reference domains, TYTAN achieves 100% coverage of important entities and attributes, and 100% correct retrieval of self-generated claims.

The system's reliance on both structural analysis and semantic reasoning underscores a critical point: structure alone is not enough. The semantic layer — the human-readable meaning of what each field and table represents — is what makes the difference between a schema the AI can inspect and one it can genuinely understand.

Isee: Interactive semantic enrichment

The Isee system focuses specifically on the quality of field descriptions. It evaluates descriptions across five dimensions — usability, informativeness, clarity, conciseness, and readability — and uses a taxonomy-guided clarification process to elicit missing domain knowledge from human experts.

A key insight from Isee: many field descriptions remain ambiguous or incomplete because essential context originates from users' domain knowledge and is rarely documented publicly. This is exactly the situation in most FileMaker deployments, where decades of institutional knowledge live in the heads of a few power users, not in the database itself.

How FileMaker 2026 Solves This

Claris recognized this problem and built annotation capabilities directly into FileMaker 2026 (v26). Here is what changed and why it matters.

GetTableDDL: The bridge to AI

The GetTableDDL function generates a SQL Data Definition Language representation of your FileMaker schema. SQL DDL is a language that LLMs already understand fluently. By translating your FileMaker tables and fields into DDL, the function creates a "semantic contract" between your database and any AI model.

Without annotations, GetTableDDL returns all fields with their names and types. With annotations, it returns only the annotated fields — each accompanied by the plain-English description you provided.

This selective behavior is intentional: it gives you fine-grained control over what schema information is exposed to a model, reducing token usage and focusing the AI's attention on the fields that matter.

Field annotations (new in v26)

FileMaker 26 introduced a dedicated field annotation interface in the Advanced Options dialog. This is separate from field comments, which means you can annotate fields for AI consumption without polluting the comments that human developers use for their own documentation.

The annotation can include:

  • What the field represents in business terms
  • How its values should be interpreted
  • Business rules, constraints, or formulas that affect its behavior
  • Whether it is read-only, a foreign key, or part of a workflow
  • Units, formats, or encoding conventions

The FieldAnnotation(fileName; fieldName) function lets you programmatically retrieve annotation data, and the annotations flow through the OData API metadata endpoint, making them accessible to any external tool or integration.

The "fork in the road" behavior

This is the single most important implementation detail to understand: when no field in a table is annotated, GetTableDDL returns all fields. When any field in a table is annotated, it returns only the annotated fields.

This means you must be intentional. If you annotate one field in a 40-field table, the AI will see only that one field. The recommendation from practitioners like Beezwax is clear: commit to annotating every field the AI will need in a table, or leave the table unannotated until you are ready.

FOREIGN KEY support in FQL

FileMaker 2026 added FOREIGN KEY syntax to its query language (FQL) DDL statements. This allows developers to express relational intent using standard SQL semantics — a language that LLMs understand natively. When an AI model receives a DDL statement with FOREIGN KEY declarations, it can reason about relationships, generate correct JOIN clauses, and produce more reliable queries.

OData metadata enrichment

The OData API metadata endpoint in FileMaker Server 26 now returns field comments, AI annotations, field options, and scripts. This means any external tool — from Power BI to a custom AI agent — can discover not just the structure of your database but the semantic context behind each field.

How to Annotate Your Database: A Practical Approach

You do not need to annotate every field in your system on day one. The goal is strategic coverage — annotating the fields and tables that AI tools, reports, dashboards, or users are most likely to interact with.

Step 1: Identify high-value tables

Start with the tables that matter most for reporting, search, workflows, or decision-making. In most FileMaker systems, this includes:

  • Orders / Jobs
  • Customers / Contacts
  • Inventory / Products
  • Invoices / Financials
  • Projects / Service Requests

Step 2: Prioritize fields by risk

Not every field needs an annotation. Focus on fields where ambiguity leads to errors:

Annotate these first:

  • Foreign key fields, especially when the relationship is not obvious from the name
  • Status and flag fields where encoded values carry specific meanings
  • Calculation fields whose business logic is not self-evident
  • Fields with non-obvious formats (percentages as whole numbers, dates in unusual formats, embedded carriage returns)
  • Fields that drive visibility or behavior in web apps

Low priority for annotation:

  • Simple text fields with clear names (s_Name, s_Email)
  • Standard timestamp audit fields
  • Clear serial primary key fields
  • Calculations whose formula is obvious from the name

Step 3: Write annotations that add value

A good annotation answers three questions:

  1. What is this? — The business meaning of the field
  2. How should I use it? — Constraints, formats, valid values
  3. What does it connect to? — Relationships and dependencies

Example annotations:

Field Annotation
b_Active "Boolean flag. 1 = record is active and visible in the system, 0 = archived/soft-deleted. Always filter on this field when querying."
n_Status "Order status code. 1=Pending, 2=Processing, 3=Shipped, 4=Delivered, 5=Cancelled. Mapped from ValueList 'OrderStatus'."
fk_CustomerID "Foreign key linking to Customers table. One customer can have many orders (one-to-many)."
n_TaxRate "Tax rate stored as a decimal fraction. 0.07 = 7%. Used in invoice line total calculation: Quantity * Price * (1 + n_TaxRate)."
s_DueDate "Date the order is expected to ship. NOT the customer-requested date — see s_RequestedShipDate for that."

Step 4: Test with an LLM

After annotating, use GetTableDDL to generate the DDL and feed it to an LLM. Ask it questions about your data and evaluate the answers. If the AI misinterprets a field, refine the annotation. This is an iterative process — the research literature confirms that iterative refinement produces dramatically better results than one-shot documentation.

Beyond FileMaker: Why Every Business Database Needs This

The annotation challenge is not unique to FileMaker. DBAutoDoc's authors observe that a tremendous number of critical database systems lack adequate documentation. Declared primary keys are absent, foreign key constraints have been dropped for performance, column names are cryptic abbreviations, and no entity-relationship diagrams exist.

Whether you run FileMaker, SQL Server, PostgreSQL, MySQL, or a custom application, the same principle applies: an AI model can only work with data it can understand, and it can only understand data that has been described.

The trend across the industry is clear:

  • Database vendors are building AI-aware metadata features (like FileMaker 26's field annotations)
  • Research institutions are developing tools for automated schema documentation (DBAutoDoc, TYTAN, Isee)
  • Organizations are investing in semantic layers and data catalogs to make their databases AI-ready

The companies that annotate their databases now will have a structural advantage when AI tools become standard in business operations. The companies that wait will find themselves rebuilding documentation under pressure — or worse, connecting AI to undocumented schemas and dealing with the consequences.

What Happens When You Get It Right

A well-annotated database unlocks capabilities that go beyond simple AI queries:

  • Natural language interfaces: Users can ask questions in plain English and get accurate answers — "Show me all orders over $10,000 that shipped late last quarter."
  • AI-assisted development: LLMs can generate FileMaker scripts, calculations, and layouts based on a semantic understanding of the schema, not just its structure.
  • Automated documentation: Annotated schemas can generate data dictionaries, onboarding guides, and compliance documentation automatically.
  • Cross-platform integration: When your FileMaker data is described in terms that any AI system can understand, integration with other platforms becomes significantly easier.
  • Safer AI deployments: Annotations reduce the risk of confident-but-wrong answers by giving the AI the context it needs to reason correctly.

Checklist: Is Your Database AI-Ready?

Use this checklist to evaluate whether your FileMaker database is ready for AI integration:

  • The most important tables (Orders, Customers, Inventory, etc.) have table-level descriptions
  • Foreign key fields are annotated with the table they link to and the relationship type
  • Status and flag fields include a legend of all valid values and their meanings
  • Calculation fields include the business logic behind the formula, not just the formula itself
  • Fields with non-obvious formats (percentages, currencies, date conventions) document the format
  • Fields that are read-only or auto-entered are marked as such
  • Ambiguous field names are disambiguated (e.g., multiple Status fields across tables)
  • GetTableDDL returns meaningful output for your annotated tables
  • You have tested the annotated schema with an LLM and verified that queries return correct results
  • Annotations are maintained as part of your development workflow, not a one-time exercise

Frequently Asked Questions

What is the difference between a field comment and a field annotation in FileMaker?

Field comments have existed in FileMaker for years and are used by developers for internal documentation. Field annotations, introduced in FileMaker 26, are a separate metadata layer specifically designed for AI consumption. They appear in the Advanced Options dialog for each field and are included in the DDL generated by GetTableDDL. You can use both without conflict — comments for humans, annotations for AI.

Do I need to annotate every single field?

No. The recommendation from Claris and from practitioners is to focus on the fields that AI tools, reports, dashboards, or users interact with most. In most systems, this means 20–30% of fields in the most important tables. The GetTableDDL behavior (annotated fields only appear once any field is annotated) means you should annotate all the fields a specific AI workflow needs within each table.

Can't I just let the AI figure out what fields mean from their names?

This works sometimes — s_Name is probably a name, d_Created is probably a creation date. But it fails catastrophically for encoded values (Status = 3), calculated fields, foreign keys with non-obvious names, and any field where the business meaning differs from the literal name. Research shows that LLMs produce significantly more accurate results when given annotated schemas versus raw schemas alone.

How long does it take to annotate a FileMaker database?

For a typical FileMaker system with 20–30 tables, annotating the most important tables and fields takes 2–5 hours of focused work. This is a one-time investment that pays dividends every time an AI tool, new developer, or external integration interacts with the database.

Does annotation change how the database works?

No. Annotations are metadata — they describe what fields mean without changing how the system behaves. They are purely additive and do not affect data entry, calculations, scripts, or user interfaces.

What if I have both [LLM]-tagged comments and new field annotations?

When both are present for the same field, the new field annotation takes precedence. The [LLM] tag in field comments is still supported for backward compatibility with FileMaker 2025 (v22), but the dedicated annotation is the recommended approach going forward.

Can annotations be localized for different languages?

Yes. FileMaker 26 annotations support localization through custom functions that use Get(SystemLocaleElements) or similar functions to return different descriptions based on the user's system locale. This is useful for organizations with multilingual teams or global deployments.

Next Steps

Annotation is the foundation, not the finish line. Once your database is annotated, you can explore:

Start with the table that causes the most confusion in your organization. Add five annotations. Test them with an LLM. You will see the difference immediately.