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

# get_report_builder_guide

> Get the guide to a Cometly report config: fields and defaults, report types, groupings, date ranges, attribution models, sources, display options and filter syntax.

Returns the guide to a Cometly report config, the format [`add_dashboard_reports`](https://docs.cometly.com/mcp/tools/add-dashboard-reports) and [`update_dashboard_report`](https://docs.cometly.com/mcp/tools/update-dashboard-report) take. It is Markdown text, the same for every Space. It reads nothing from your Space and changes nothing.

> [!NOTE]
>
> If your client does not list this tool, it is not available on your connection: the connection is read-only, or your role in the Space is Viewer (or no longer allows changes).

## When to use

Once, before the first `add_dashboard_reports` or `update_dashboard_report` call of a conversation.

## Parameters

None.

## Output

Markdown with these sections:

| Section | What it lists |
| - | - |
| Fields | Every config field, whether it is required, and the value it gets when left out. |
| `report_type` | Each report type, how many `group_by` levels it takes, and what it is for. |
| `group_by` | Time buckets, other groupings, and the custom contact fields. |
| `date_range` | Every accepted range, and which ones need `date_start` or `date_end`. |
| `attribution_model` | Every accepted model, with a one-line explanation. |
| `sources` | Every accepted source value. |
| `options` | The display options a report accepts. |
| `filters` | The filter structure and the operators for text, number, date and source fields. |
| A complete call | An example `add_dashboard_reports` call. |

The lists of accepted values are generated from the same code the server checks a config with, so the guide matches what the server accepts.

The output starts like this:

```markdown theme={null}
# Cometly report builder guide

A report on a Cometly dashboard is one JSON object, the config. `add_dashboard_reports` takes a list of them; `update_dashboard_report` takes only the fields to change. ...
```

## Not covered

What belongs to a Space is not in the guide. Get it from these tools:

* Metric slugs, including the Space's user-defined metrics: [`list_metric_catalog`](https://docs.cometly.com/mcp/tools/list-metric-catalog).
* Custom events: [`list_custom_events`](https://docs.cometly.com/mcp/tools/list-custom-events).
* Filter keys: [`list_filterable_fields`](https://docs.cometly.com/mcp/tools/list-filterable-fields).
* An existing report's config, to copy or adapt: [`get_report_definition`](https://docs.cometly.com/mcp/tools/get-report-definition).

## Availability

Offered together with [`create_dashboard`](https://docs.cometly.com/mcp/tools/create-dashboard), [`add_dashboard_reports`](https://docs.cometly.com/mcp/tools/add-dashboard-reports) and [`update_dashboard_report`](https://docs.cometly.com/mcp/tools/update-dashboard-report). Like them, it is hidden from [read-only connections](https://docs.cometly.com/mcp/authentication.md#read-only-tokens), which include every connection made by a Viewer, because it describes tools those connections don't have. Calling it there returns "Tool not found".


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.