# list_macros


> List table and scalar macros in a MotherDuck database with their parameters

List all macros (table and scalar macros) in a MotherDuck database with their schema and parameters.

## Description

The `list_macros` tool returns the macros defined in a specified database, including their schema, type, and parameter names. You can optionally filter by schema or keywords. Macros encapsulate reusable SQL logic; knowing which ones exist helps the AI assistant reuse them instead of rebuilding the logic in every query.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database name to list macros from |
| `schema` | string | No | Schema name (defaults to all schemas) |
| `keywords` | string | No | Filter macros by name (case-insensitive, any word can match) |
| `limit` | number | No | Maximum results to return (default: 100, maximum: 500) |

## Output schema

```json
{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema filter used ("all" if not specified)
  "macros": [                    // List of macros (on success)
    {
      "schema": string,          // Schema name
      "name": string,            // Macro name
      "type": string,            // Macro type
      "parameters": [string]     // Parameter names
    }
  ],
  "count": number,               // Number of macros returned
  "totalCount": number,          // Total number of matching macros
  "truncated": boolean,          // Present when results were cut to fit the limit
  "error": string                // Error message (on failure)
}
```

## Example usage

**List all macros in a database:**

```text
Are there any reusable macros in analytics_db?
```

The AI assistant will call the tool with:

```json
{
  "database": "analytics_db"
}
```

**Filter by keywords:**

```json
{
  "database": "analytics_db",
  "keywords": "fiscal"
}
```

## Success response example

```json
{
  "success": true,
  "database": "analytics_db",
  "schema": "all",
  "macros": [
    {
      "schema": "main",
      "name": "fiscal_quarter",
      "type": "macro",
      "parameters": ["date_col"]
    }
  ],
  "count": 1,
  "totalCount": 1
}
```

## Related

- [`list_views`](../list-views) — List views in a database.
- [`list_tables`](../list-tables) — List tables and views with their comments.
- [`query`](../query) — Run a query that uses a macro.


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmcp%2Fcore%2Flist-macros%2F&page_title=list_macros&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.