> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data dictionary

> Bundle real-world data documentation with your service for AI agents and app integrations

A data dictionary is a markdown document bundled with a service that describes its real-world data patterns, field conventions, relationships, and sample data. It provides context that tool schemas alone cannot — actual enum values, ID format patterns, nullable fields in practice, and relationship cardinality.

## Why it matters

Tool schemas define how to call a service, but not what the data looks like in practice. The gap varies by service type:

**API services** (Shopify, GitHub, Slack) — tool schemas describe the available resources, but the data dictionary adds real-world patterns: a `status` field is actually an enum with values `active`, `draft`, and `archived`; product IDs use Shopify GID format like `gid://shopify/Product/123456789`; the `metadata` field contains parseable JSON.

**Data platform services** (Snowflake, PostgreSQL, Elasticsearch) — tool schemas only describe how to run queries. They contain no information about what tables exist in the account, what columns those tables have, how tables relate to each other, or what the data means. The data dictionary bridges this gap entirely — documenting the account's schema, table relationships, column semantics, and sample data so that AI agents can construct meaningful queries.

AI agents and apps call `get_data_dictionary` before using a service to understand these patterns.

## Structure

The data dictionary is defined in `src/dataDictionary.ts`:

```typescript theme={null}
export const DATA_DICTIONARY = `
# Data Dictionary: My Service

> Generated on: 2026-01-28

## Overview
Brief description of the service and its data model.

## Quick Reference
| Resource | Description | Key Fields | Notable Patterns |
|----------|-------------|------------|------------------|
| Products | Product catalog | id, title, status | ID format: \`gid://shopify/Product/{id}\` |
| Orders   | Customer orders | id, status, total | Status: open, closed, cancelled |

## Resources

### Products
| Field | Type | Nullable | Description | Example Values | Conventions |
|-------|------|----------|-------------|----------------|-------------|
| id | string | No | Product identifier | \`"gid://shopify/Product/123"\` | Shopify GID format |
| title | string | No | Product title | \`"Classic T-Shirt"\` | |
| status | string | No | Publication status | \`"active"\`, \`"draft"\`, \`"archived"\` | Enum |

## Relationships
Products have many Variants. Orders have many Line Items, each referencing a Variant.

## Field Conventions
### ID Fields
- Products: \`gid://shopify/Product/{numeric_id}\`
- Orders: \`gid://shopify/Order/{numeric_id}\`

### Status Fields
- Product status: active, draft, archived
- Order financial status: pending, paid, refunded, voided
`;

export const DATA_DICTIONARY_GENERATED_AT = "2026-01-28T00:00:00Z";
```

## The get\_data\_dictionary tool

The data dictionary is exposed at runtime through a `get_data_dictionary` tool so that AI agents and apps can retrieve it before interacting with the service.

### Tool definition

```typescript theme={null}
get_data_dictionary: {
  name: "get_data_dictionary",
  description: "Get the data dictionary documentation for this service. Use this to understand the data structure, field conventions, relationships, and sample data patterns before querying the service.",
  inputSchema: {
    type: "object",
    additionalProperties: false,
    properties: {},
  },
  outputSchema: {
    type: "object",
    additionalProperties: true,
    properties: {
      success: { type: "boolean" },
      content: { type: "string", description: "The full data dictionary markdown content" },
      generatedAt: { type: "string", description: "When the data dictionary was generated" },
    },
    required: ["success", "content"],
  },
},
```

### Handler

```typescript theme={null}
private async getDataDictionary(): Promise<any> {
  try {
    const { DATA_DICTIONARY, DATA_DICTIONARY_GENERATED_AT } = await import("./dataDictionary");
    return {
      success: true,
      content: DATA_DICTIONARY,
      generatedAt: DATA_DICTIONARY_GENERATED_AT,
    };
  } catch {
    return {
      success: false,
      error: "Data dictionary not found",
      details: "Run the data_explorer tool to generate the data dictionary.",
    };
  }
}
```

## Content guidelines

A good data dictionary documents what schemas cannot:

| Category         | API services                                        | Data platform services                       |
| ---------------- | --------------------------------------------------- | -------------------------------------------- |
| ID formats       | Prefixes, GID patterns, UUID vs numeric             | Primary key types and naming                 |
| Enum values      | Actual values for status, type, and category fields | Column value ranges and categories           |
| Schema discovery | Which fields are nullable in practice               | Tables, columns, types, and descriptions     |
| Relationships    | Foreign key patterns and cardinality                | Joins, foreign keys, and dimensional models  |
| Sample data      | Representative records showing real-world values    | Example rows illustrating column semantics   |
| Conventions      | Date formats, currency handling, pagination         | Naming conventions, partitioning, warehouses |