PostgreSQL COMMENT ON: A Practical Guide for AI Agents

A new tagging convention for PostgreSQL COMMENT ON statements using @ai, @policy, and @example tags enables AI agents to treat database comments as machine-readable instructions, with strict placement rules requiring tags at the start of a line and one per line. The approach, advocated by Kozou via MCP, moves intelligence into the data layer so agents inherit business logic and constraints regardless of frontend.

PostgreSQL COMMENT ON: A Practical Guide for AI Agents COMMENT ON .If you use tools like Kozou via MCP /en/tags/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. Next MCP Tool Pinning: A Compatibility Guide → /en/threads/2705/