create-report

name	create-report
description	Create a report using Motley.

Create Report

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

Overview

Motley helps to create reports based on the user's data and requirements.

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 report creation workflow has 3 phases:

1. Research & Plan — understand the user's needs & the relevant data
2. Creating a document in Motley – based on the research, write the report content into a document
3. Output and iteration – show the report to the user, ask for feedback, and iterate until it's ready

The end result of the workflow is a document in Motley (can be opened via link) and, secondarily, a Markdown export of it.

---

Phase 1: Research & Plan

Enter plan mode.

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

Explore Models

Data is central to the report generation. It can be used both for charts and inline queries embedded in the text.

The purpose of this step is to find the relevant data for the queries and charts that should be in the report. Data is represented as models (data models), containing measures and dimensions, that can be queried.

Understand what models are available:

models_summary()

Then inspect relevant models to see measures, dimensions, and sample data:

inspect_model(model_name="revenue", num_rows=3)
inspect_model(model_name="customers", num_rows=3)

If existing models don't have the data you need, you can declare new saved measures on the model via create_measure, edit measure formulas with patch_measure, or declare joins with create_join. Use validate_formula to syntax-check DSL expressions before committing. See the explore-model skill for the full model-edit toolkit.

Ask questions

Until it's completely clear what the user wants, ask them questions.

If it's unclear from where the data should come, ask them to point exactly.

If anything about the data is ambiguous, ask them for clarification, also listing the possible options.

---

Phase 2: Create a document in Motley

A document is a flat sequence of text (Markdown) blocks, table blocks, and charts. Text and table blocks can reference queries.

To create a document, use the create_document tool:

create_document(
    name="<descriptive name>",
    source_id=<source_id>
)

You need to provide the source_id of the models you are going to use. Currently, all the models in a document must come from a single source. The source_id can be found in outputs of models_summary and inspect_model tools.

Document lifecycle

• rename_document(document_id=<id>, new_name="<new title>") — change a document's title. Empty/whitespace-only names are rejected.
• delete_document(document_id=<id>) — soft-delete. The document is hidden from list_resources(what="documents") and inspect_document returns a 404 afterwards. Idempotent on already-deleted docs (also returns 404).

Set Context Variables

Documents have global variables substituted into queries (filters) and text blocks ({var_name}) at resolution time. Use them for anything that might change on a re-run (customer, region, etc.) so the report can be regenerated by swapping values.

Required variables:

• start_date / end_date — always required (used by query time filtering); often it's all you need
• Source-specific variables from parametrized default filters — required when the source declares them

Available/required variables appear in create_document response and in get_doc_variables response. New variables can also be created as needed.

set_doc_variables(
    doc_id=<id>,
    variables={"start_date": "2025-01-01", "end_date": "2025-12-31", "foo": "bar"}
)

Merges with existing values and re-resolves all blocks. Only provide keys you want to change.

Create Blocks

Creating blocks and updating them is done using the tools:

• update_text_block
• update_table_block
• update_chart_block
• update_query_block

Each block must have a unique name by which it can be referenced. To create a new block provide a new, unique name.

Other block operations: move_block (reorder), rename_block (rename in place, updates references), delete_block (remove a block), delete_query (remove a child query from its parent).

Scratch lookups

Before authoring a query/chart block, use run_query to sanity-check the data without persisting anything:

run_query(
    source_id=<id>,
    query={"subqueries": [{"source_model": "orders", "measures": ["created_at:min", "created_at:max", "*:count"]}]},
    limit=5
)

Useful for: confirming a column exists and has data, finding the date range, sanity-checking a measure formula, picking sensible default start_date/end_date for the document. Same query shape as update_query_block / update_chart_block; no block is created, no document is touched. Optional variables={"name": "value"} resolves {var} placeholders in filters.

Chart Blocks

Queries use the SLayer schema — measure/filter formulas are DSL strings, wrapped in subqueries:

update_chart_block(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<chart_block>"},
    query={
        "subqueries": [{
            "source_model": "orders",
            "measures": ["revenue:sum"],
            "time_dimensions": [{"column": "created_at", "granularity": "month"}],
            "order": [{"column": "created_at", "direction": "asc"}]
        }]
    },
    chart_details={
        "title": "Monthly Revenue",
        "series_default": {"type": "line", "y_axis": "left",
                           "number_format": {"type": "currency", "symbol": "$", "precision": 0}},
        "xAxis": {"label": false, "lines": false},
        "yAxis": {"label": "Revenue", "lines": true},
        "legend": {"enabled": false}
    }
)

Then verify:

render_chart(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<chart_block>"}
)

See the update-chart skill for chart type guidance and configuration patterns.

Text Blocks

First create query blocks for the data:

update_query_block(
    location={doc_id: <id>, slide_name: "<slide>", parent_block: "<text_block>"},
    query_name="<name>",
    query={<query_config>}
)

Then set the template:

update_text_block(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<text_block>"},
    user_prompt="<template with {variables}>",
    call_llm=<true/false>
)

Verify the text block by checking the returned content. See the update-text-block skill for template syntax and modes.

Table Blocks

Same pattern as text — create query blocks first, then set the template:

update_query_block(
    location={doc_id: <id>, slide_name: "<slide>", parent_block: "<table_block>"},
    query_name="<name>",
    query={<query_config>},
    mode="table"
)

update_table_block(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<table_block>"},
    user_prompt="{<query_name>}"
)

See the update-table-block skill for table patterns.

---

Phase 3: Output and iteration

Export as Markdown and review

Export the document to markdown format:

export_document(document_id=<id>, format="markdown", mode="table")

This will embed the data for the charts as markdown tables, with chart metadata next to them.

Check the output carefully. Does it look as expected? If not, go back and update the blocks.

Render for the user

Show the user the rendered document as markdown. Show a button to open the document in Motley. Ask the user for feedback.

If the user wants to make changes, understand the feedback and go back and update the blocks, then render again.

The Motley document is the result of this workflow.

(Optional) Export to another format

On user request, export the report to the user's preferred format.

If available, you can use the frontend-slides skill to create a presentation using the content of the document.