PostgreSQL COMMENT ON: A Practical Guide for AI Agents

Raw DDL is rarely enough for an LLM agent to navigate a complex database without hallucinating. An agent can read column names and types, but it has no way of knowing which column is a deprecated "trap" or which view is the actual source of truth. In my experience rolling this out for my team, the most effective way to fix this is by embedding the meaning directly into the database using COMMENT ON.

If you use tools like Kozou via MCP, these comments become the primary instructions for the agent. Even without specific tools, treating your DB comments as a knowledge base is a solid architectural move.

The Tagging Convention

To make these comments machine-readable and useful, use specific tags at the start of a line. If a tag is placed mid-sentence, it's often ignored or treated as plain text.

• @ai: Direct instructions or background context for the agent.
• @policy: Business rules (advisory, not enforced by the DB).
• @example: Executable query examples (typically attached to views).

A few technical constraints to keep in mind:
1. Strict Placement: Tags must be at the beginning of the line.
2. One per line: Stack multiple @ai: lines if you have several points; don't bunch them together.
3. ASCII Colons: Always use the standard : colon. Using full-width characters (common in Japanese/Chinese input) will cause the tag to be ignored silently.

Practical Implementation: @ai

The goal with @ai isn't to describe the data, but to dictate behavior. Use the imperative mood to tell the agent what to do—and more importantly, what to avoid.

For example, if you have a denormalized column that is no longer reliable, don't just call it "deprecated." Tell the AI to ignore it:

COMMENT ON COLUMN orders.amount_total IS 'DEPRECATED denormalized order total.
@ai: Do NOT use this column for calculations. Use the order_items table instead.';

By explicitly naming the "trap," you prevent the agent from taking a shortcut that leads to incorrect data.

AI Workflow and Discoverability

This approach fundamentally changes the AI workflow. When an agent performs a schema search, it isn't just looking at table names; it's indexing the @ai and @policy notes. The keywords you use in these comments become the "handles" the agent uses to discover the correct path to the data.

Instead of writing long, rambling prompts in your application code, you move the intelligence into the data layer. This ensures that any agent connecting to the DB—regardless of the frontend—inherits the same business logic and constraints.