---
name: create-report
description: >
  Create a data-driven report as a Motley document. Explore the semantic
  layer, author queries, charts, tables, and text blocks, then iterate
  with the user. Use when the user asks for a report, analysis, or any
  data-driven document built on their data.
---

# Create Report

End-to-end workflow for creating a data-driven report using Motley.

A **report** in Motley is a document consisting of blocks (markdown text, tables, and charts).
Blocks can reference data queries, other blocks, and context variables.

The workflow has 3 phases:

1. **Research & Plan** — understand the user's needs & the relevant data
2. **Create a document in Motley** — write the report content into a document
3. **Output and iteration** — show the report to the user and iterate until it's ready

The end result is a document in Motley (openable via link) and, secondarily, a Markdown export of it.

The MCP tool schemas and Motley's built-in help are the reference documentation —
this skill only describes the workflow. If Motley is unfamiliar, start with
`inspect(reference="memory:help.intro", entity_type="memory")`: concepts, the
query shape, gotchas, and the deep-dive topics (`memory:help.queries`,
`memory:help.workflow`, ...).

---

## Phase 1: Research & Plan

Enter plan mode.

Make sure you understand **why** the user wants this report and **what** exactly they want to show.

### Explore the data

Always start with `search(question="...")` — it ranks models, columns, measures,
and saved memories in one call. A memory from an earlier session may already
record the right model, a verified example query, or a gotcha.

Then inspect: `inspect(entity_type="model")` lists all models;
`inspect(reference="<model>", entity_type="model", num_rows=3)` shows one model's
columns, measures, and sample rows. `list_resources(what="datasources")` gives the
`source_id`s.

If existing models lack something, extend them with `edit_model` (upserts
measures, columns, and joins atomically). Syntax-check DSL formulas with
`validate_formula` before committing.

### Scratch lookups

Before authoring any block, sanity-check the data with the `query` tool — same
query shape as the block tools, nothing persisted. Typical probe:
`measures=["<time_col>:min", "<time_col>:max", "*:count"]` to confirm a column
has data and find the date range, and to pick sensible default
`start_date`/`end_date` for the document.

### Ask questions

Until it's completely clear what the user wants, ask them questions.
If it's unclear where the data should come from, ask them to point exactly.
If anything about the data is ambiguous, ask for clarification, listing the possible options.

---

## Phase 2: Create a document in Motley

Create the document with `create_document(name=..., source_id=...)`. All models
in a document must come from a single source. The document starts blank, as a
single-slide deck; inspect it any time with `inspect_document`.

### Context variables

Documents have global variables substituted into queries (filters) and templates
(`{var_name}`) at resolution time. Use them for anything that might change on a
re-run (customer, region, dates) so the report can be regenerated by swapping
values. `start_date` / `end_date` are always required; source-specific variables
may be too — check `get_doc_variables`, set values with `set_doc_variables`.

In block queries, leave the wrapper `start_date`/`end_date` unset so the
document's variables apply.

### Create blocks

Blocks are created and updated with `update_text_block`, `update_table_block`,
`update_chart_block`, and `update_query_block`. Each block needs a unique name;
providing a new name creates a block. Reorganize with `move_block`,
`rename_block`, `delete_block`, `delete_query`.

Queries everywhere use the SLayer shape described in `memory:help.queries`.

**Charts** — call `update_chart_block` with a `query` and `chart_details`, then
**verify visually** with `render_chart`.

**Text** — two steps: first attach data with
`update_query_block(parent_location=..., query_name=..., query=...)`, then set
the template with `update_text_block`. Check the returned resolved content.

**Tables** — same two steps, with `mode="table"` on the query (optionally
`pivot_dimension`), then `update_table_block` with a template like
`"{<query_name>}"`.

### Template syntax

In `user_prompt` of text and table blocks:

- `{name}` — the value of a child query (its `query_name`) or a context variable.
- Arithmetic on numeric variables: `{revenue / users}`.
- `{Slide::Block}` — content of a block on another slide. Referencing a chart
  block embeds its data as a markdown table.
- `call_llm=true` makes the LLM write the content from the referenced data. In
  that mode, reference data with the directive `:var[{value}]{name="<query_or_block>"}`
  — at least one such reference is required. Leave `call_llm=false` when the
  template already is the final text.

---

## Phase 3: Output and iteration

Export with `export_document(document_id=..., format="markdown", mode="table")` —
chart data is embedded as markdown tables. Check the output carefully; if
something is off, go back and update the blocks.

Show the user the rendered document as markdown, with a button to open it in
Motley. Ask for feedback and iterate. The Motley document is the result of this
workflow.

If the user confirmed a non-obvious number or query, save it with `save_memory`
(attach the query) so future sessions can reuse it.

On request, export the document to another format with `export_document`.