# Tool Generation (/docs/datasets/tool-generation)

`@hypequery/datasets` can generate tool metadata from the same catalog used by Serve and MCP. Use this when an agent runtime needs constrained schemas for dataset queries instead of direct access to SQL.

Generated tools expose declared datasets, dimensions, measures, filters, order fields, time grains, and limits. They do not expose tenant selection by default, and SQL is removed from tool results unless `includeSql` is enabled.

## Catalog Tool [#catalog-tool]

Catalog mode creates one generic `query_dataset` tool.

<CodeBlock>
```typescript
import { createDatasetClient } from '@hypequery/datasets';
import { generateDatasetTools, toOpenAITools } from '@hypequery/datasets/schemas';
import { Orders } from './datasets/orders.js';
import { db } from './db.js';

const analytics = createDatasetClient({ queryBuilder: db });

const tools = generateDatasetTools({
  datasets: { orders: Orders },
  analytics,
  mode: 'catalog',
});

const openaiTools = toOpenAITools(tools);
```
</CodeBlock>

The generated schema includes enums derived from the dataset catalog. Queryable [relationship fields](/docs/datasets/relationships) (for example `customer.country`) appear in the dimension, filter, and order enums alongside local dimensions.

<CodeBlock>
```json
{
  "name": "query_dataset",
  "parameters": {
    "type": "object",
    "properties": {
      "dataset": { "type": "string", "enum": ["orders"] },
      "dimensions": {
        "type": "array",
        "items": { "type": "string", "enum": ["status", "createdAt"] }
      },
      "measures": {
        "type": "array",
        "items": { "type": "string", "enum": ["revenue", "orderCount"] }
      }
    },
    "required": ["dataset"],
    "additionalProperties": false
  }
}
```
</CodeBlock>

## Per-Dataset Tools [#per-dataset-tools]

Per-dataset mode creates one tool per dataset, such as `query_orders`.

<CodeBlock>
```typescript
const tools = generateDatasetTools({
  datasets: {
    orders: Orders,
    customers: Customers,
  },
  analytics,
  mode: 'per-dataset',
});
```
</CodeBlock>

## Adapters [#adapters]

Use adapters when a runtime needs a specific metadata shape.

<CodeBlock>
```typescript
import {
  toAISDKTools,
  toMcpTools,
  toOpenAITools,
} from '@hypequery/datasets/schemas';

const openaiTools = toOpenAITools(tools);
const aiSdkTools = toAISDKTools(tools);
const mcpTools = toMcpTools(tools);
```
</CodeBlock>

`toAISDKTools()` returns plain tool objects with `description`, `parameters`, and `execute`. If your AI SDK version expects a wrapper such as `tool(...)`, wrap the returned entries in your application.

## SQL Redaction [#sql-redaction]

Generated tools redact `meta.sql` by default.

<CodeBlock>
```typescript
const tools = generateDatasetTools({
  datasets: { orders: Orders },
  analytics,
  includeSql: false,
});
```
</CodeBlock>

Set `includeSql: true` only for trusted debugging contexts.

## Validation [#validation]

Tool execution performs catalog-level validation before calling `analytics.execute(...)`. Invalid datasets, fields, filter operators, order fields, grains, and limits fail with errors that agents can repair.

The dataset client remains the authoritative validator and executor. Tool generation is a constrained metadata and execution wrapper around the same semantic query path.