Flourish

Create a new visualisation given a template id. Visualisation will be initialised with template’s sample data and default settings.

flourish_create_visualisation

Duplicate a visualisation. Creates a copy with all data and settings preserved.

flourish_duplicate_visualisation

Get template info including description, categories, dataset specs, data binding specs and sample data.

flourish_get_template_details

Read a paginated slice of a visualisation's data table. Call flourish_get_template_details first to discover dataset ids. For multi-dataset visualisations, specify which dataset; for single-dataset visualisations dataset is optional. Default limit is 100 rows, max 500. Use total_rows + offset to page through larger datasets. Cells longer than 500 characters are shortened with a "...[truncated, original N chars]" marker. There is currently no way to retrieve full cell values via this tool — if you need them (e.g. for a data transformation workflow), ask the user to access the source data directly.

flourish_get_visualisation_data

Get a visualisation's settings — every setting declared by the template, with the user-set current_value attached when present. Returns a flat array including each setting's schema metadata (choices, min/max, requires/inactive_when, optional flag). Use filter to narrow the results by a whitespace-separated list of terms; each term is a case-insensitive substring match against id, name, section, subsection, description, and choice labels, and results are ranked by how many terms matched. Responses are capped by `limit` (default 30). `total_matched` in the response reports how many settings matched — when it's larger than the returned array, refine the filter or raise `limit`. Settings are grouped hierarchically: every setting carries a 'section' label (the main group it lives under, e.g. "Chart type"), and some also carry a 'subsection' label (a named sub-group inside a section, e.g. "Advanced"). Subsection is optional — settings without an explicit named subsection simply have no subsection field. Settings may carry 'requires' and/or 'inactive_when' — a condition describing what must hold (or must not hold) for the setting to take effect on the rendered chart. Writes to a setting whose conditions aren't met are accepted but inert until they become true. Some settings may carry 'read_only: true' — these are hidden settings in the Flourish editor. They're surfaced so that agents can look up their current values when another setting's 'requires' or 'inactive_when' references them; attempts to update a read_only setting are rejected. A condition is an object whose keys are property names ANDed together. A value is either a scalar (equality) or an array (any-of). Reserved operator keys: 'any_of': [conditions] is OR across alternatives, 'all_of': [conditions] is AND across alternatives (used only when a flat object can't express the conjunction — e.g. when sub-conditions share a key or one is itself an any_of). Keys starting with 'data.' reference a binding rather than a setting.

flourish_get_visualisation_settings

List Flourish templates available for creating new visualisations. There are dozens of templates available that can be used for charts, maps, or other interactive visualisations. Some templates support multiple chart types, e.g. "line-bar-pie" can be configured as a line/area/pie/bar/column chart, and many other variations. Results are ordered by priority: Flourish-owned templates appear first, followed by the authenticated user's own templates, then templates owned by members of the user's company, then other templates. When multiple results share the same external_id, they are different versions or owner copies of the same template family. Use this tool when the user wants to: * browse available visualisation templates or chart types * find a template by name * list template names or categories that match a search term When selecting a template to use (e.g. for create_visualisation), prefer the first result for a given external_id as it is the highest-priority version. If multiple candidates exist for the same template family and the choice is ambiguous, confirm with the user which version they want before proceeding.

flourish_list_templates

List the authenticated user's Flourish visualisations with optional filtering and pagination. Returns names, template name, edit URLs, publication status, and last-updated timestamps — ordered most-recently-updated first. Use this tool when the user wants to: * browse or search their existing visualisations * find a visualisation by name or template * check which visualisations are published

flourish_list_visualisations

Replace a visualisation's data with CSV provided inline as a tool argument. The first CSV row is treated as column headers. This tool is suitable for small datasets: up to ~100 KB and ~1,000 data rows. These limits apply to the data actually being uploaded, including the result of any aggregation, filtering, or summarisation applied to a larger source. Uploading needs the complete dataset rather than a truncated sample, so it assumes the source data has been read in full. Datasets larger than these limits are rejected by the server and are better imported through the Flourish editor: open the visualisation's edit page (https://app.flourish.studio/visualisation/<visualisation-id>/edit), open the Data tab, and choose "Import data" to upload the CSV. When the server rejects an oversized upload it returns this same guidance in its error response, ready to relay to the user; re-sending the same data after a size rejection will fail again. For templates with multiple datasets (e.g. Bar Chart Race), the dataset parameter selects which data table to update; it is optional for single-dataset templates. Changing the data's shape (dropping or reordering columns) can leave existing bindings pointing at columns that no longer exist. After a successful upload the result lists any such bindings under invalid_bindings, which can be reconfigured with flourish_update_visualisation_data_bindings.

flourish_update_visualisation_data

Update a visualisation's data bindings, which control the columns used for each visual variable (axis labels, values, colours, facets etc.). The template's available binding keys, whether each is required or optional, and the data types each accepts are reported by flourish_get_template_details. Each binding key maps a visual variable (e.g. 'label', 'value', 'color', 'x', 'y') to one or more data columns by 0-based index, and a binding accepts columns whose type is one of its data_types (e.g. a binding with data_types ["number", "datetime"] accepts a number or datetime column). Setting columns to [] clears a binding: this is always allowed for multi-column bindings, and allowed for single-column bindings only when the binding is optional.

flourish_update_visualisation_data_bindings

Update settings on a visualisation. Each entry in the settings object maps a setting id to its new value. Available setting ids, types, choices, and conditions are reported by flourish_get_visualisation_settings. Validation is strict and all-or-nothing for hard errors: an unknown id, wrong-typed value, out-of-range number, invalid choice, or refuted precondition (requires / inactive_when where a referenced setting has a stored value that disagrees) causes the call to fail with no settings written. Preconditions are evaluated against the merged post-update state, so a prerequisite setting supplied in the same call can satisfy another setting's precondition; when a precondition is unmet the error reports the conditions involved. If a precondition references settings that have no stored value, the write is applied and a warning is returned in data.warnings — the change may not be visible on the rendered chart if the template's runtime state doesn't satisfy the precondition. If the change doesn't take effect, retry (if it seems appropriate) with those settings' values included in the same call. For example if a precondition is 'show_scale_settings' it's safe to set it, but if it's something like 'chart_type', report back to the user. Null values are rejected. Notes on common settings: - Units: a setting's description may specify pixels or rems. Across Flourish templates, rem is the house style for fonts, labels, and most layout dimensions; pixels are reserved for data-mark dimensions (data points, nodes), low-level strokes/borders, and table cell minimums; percentages are reserved for radii and inner-padding ratios. - Backgrounds: when switching the background colour between light and dark, the text colours (title, subtitle, labels, tick_label_color) and line colours (gridline_color, line_and_tick_color) usually need updating too so contrast is maintained. - Highlighting: colour is the primary means of emphasis. Highlighting a specific series or category usually works best alongside de-emphasising the others (e.g. setting non-highlighted ones to grey). - Number display: number formatting settings control prefix/suffix (e.g. '$', '%', 'M'), decimal places, and multiply/divide. Thousands and decimal separators are set on the Data tab and cannot be changed via settings. - Titles: an effective title conveys the chart's key takeaway in roughly twelve words or fewer; subtitles are factual descriptions of the data. - Fonts: font type settings take an object { name: <font name>, url: <font CSS URL> }. For Google Fonts supply the Google Fonts CSS URL (e.g. "https://fonts.googleapis.com/css?family=Roboto"). For visualisations with a company theme the current_value already carries the correct custom font name and URL — pass that object back unchanged to preserve it.

flourish_update_visualisation_settings