create_client, list_reports,
add_data_widget — so an agent can guess the right one from the action.
Every tool also carries a title and read-only / destructive hints, so a client can show what a
tool will do before it runs.
Tool catalog
Account
| Tool | What it does |
|---|---|
get_account | Get account details for the authenticated user |
get_account_usage | Get current account usage stats (clients, reports, users, storage) |
whoami | Who this connection is signed in as: the user, the account, the plan and how much of it is used. Call this first in a session — it answers “which account am I on?” without combining get_curr… |
Archive
| Tool | What it does |
|---|---|
list_archive | List soft-deleted (archived) items across clients, reports, media, automations and templates. |
restore_from_archive | Restore archived items of one type back to active. |
Assets
| Tool | What it does |
|---|---|
add_asset_to_page | Instantiate an asset’s widgets onto a report page. Each widget is cloned with a fresh ID and stacked below existing widgets. Widgets whose datasource / goal / calculated metric isn’t connect… |
archive_asset 🔒 | Archive a saved section and its widget rows. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
create_asset | Save widgets as a reusable section, the same way the editor does when you select widgets and save them: each widget is copied onto the section with a fresh id, and its type and datasources a… |
duplicate_asset | Duplicate an asset (and its widgets) under a new name. |
get_asset | Get a single asset by ID. |
list_asset_widgets | List the widgets that belong to an asset (useful for previewing what add_asset_to_page will instantiate). |
list_assets | List saved widget-section assets for the account (with optional filters). |
update_asset | Update asset metadata. Only include fields you want to change. |
Automations
| Tool | What it does |
|---|---|
archive_automation 🔒 | Archive an automation, stopping its scheduled deliveries. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back, rescheduled. |
create_automation 🔒 | Create a new automation. Pick an existing email template + sender by id (from list_email_templates / list_email_senders), or pass template_id:“custom” together with a custom payload to sav… |
get_automation_history | Get send history for an automation |
list_automations | List automations with optional filtering by report or client |
pause_automation | Pause an automation. It keeps its schedule and recipients but sends nothing until it is unpaused. |
test_automation 🔒 | Send a test email for an automation |
unpause_automation 🔒 | Unpause an automation. It starts emailing its recipients again on its schedule — confirm before calling. |
update_automation 🔒 | Update an existing automation — only include the fields you want to change |
Branding
| Tool | What it does |
|---|---|
get_branding | Get the account’s white-label branding (logo, favicon) |
refresh_account_favicon | Re-derive the account’s favicon from its website, cache-bust it, save it and return the new URL. Requires a website on the account (set it with update_company). |
remove_account_favicon 🔒 | Remove the account’s square logo (favicon). It falls back to the default Oviond branding. |
remove_account_logo 🔒 | Remove the account’s full logo. It falls back to the default Oviond branding. |
update_branding | Update branding settings — only include the fields you want to change. For logo_url and favicon_url, use list_media to look up a URL from uploaded media. (Brand color is no longer configurab… |
Calculated metrics
| Tool | What it does |
|---|---|
archive_calculated_metric 🔒 | Archive a calculated metric by ID. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
create_calculated_metric | Create a calculated metric — a custom KPI from a formula over other metrics. |
duplicate_calculated_metric | Duplicate a calculated metric, optionally with a new name. |
list_calculated_metrics | List calculated metrics for the account (custom KPI formulas). |
update_calculated_metric | Update a calculated metric. Full replacement — you must send name, formula AND symbol. |
Clients
| Tool | What it does |
|---|---|
archive_client 🔒 | Archive a client by ID, with its reports, exports and automations. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
archive_clients 🔒 | Archive several clients by ID in one call. They go to the archive, not away — list_archive shows them and restore_from_archive brings them back. |
count_clients | Get total count of clients for the account |
create_client | Create a new client |
get_client | Get a single client by ID |
list_clients | List all clients with optional filtering and pagination |
move_client_to_folder | Move a client to one or more folders |
refresh_client_favicon | Re-derive a client’s square favicon from its stored website (Google favicon service), cache-bust it, save it, and return the new favicon URL. Requires the client to have a website configured… |
refresh_client_screenshot | Re-take the screenshot of a client’s website and save it, returning the new URL. The screenshot is generated server-side from the stored website, so the client needs one configured. Use this… |
remove_client_favicon 🔒 | Remove a client’s square logo/favicon (favicon_url). It falls back to the agency branding. |
remove_client_logo 🔒 | Remove a client’s full logo (logo_url). It falls back to the agency branding. |
update_client | Update an existing client — only include the fields you want to change |
Company
| Tool | What it does |
|---|---|
generate_company_palette | Generate a color palette from a hex color (read-only — computes shades, changes nothing). |
get_company | Get company settings |
update_company | Update company settings |
Custom data
| Tool | What it does |
|---|---|
archive_custom_data 🔒 | Archive a custom-data dataset by ID. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
create_custom_data | Create a custom-data dataset from parsed CSV rows (max 10,000 rows). |
duplicate_custom_data | Duplicate a custom-data dataset with a new name. |
get_custom_data | Get a single custom-data dataset by ID, including its parsed rows. |
list_custom_data | List uploaded custom-data (CSV) datasets for the account — summaries without the row data. |
update_custom_data | Update a custom-data dataset — send only the fields you want to change (e.g. ). |
Datasources
| Tool | What it does |
|---|---|
connected_datasources | List the datasource connections this account has made. A widget can only pull real data from a datasource that is connected to its client — anything else renders demo data. |
create_connection | Create a datasource connection from credentials — the connect panel’s credential form, as a tool. Call it with just datasource_id to be told which fields that datasource needs, then again wi… |
datasources | List every datasource Oviond supports, with the id (the datasource_id used everywhere else — e.g. ga4, gadw, fb-ads), name, category, and data views. Call this FIRST to find the datasource… |
delete_connection 🔒 | Delete a datasource connection — every widget pulling data from it will break |
describe_datasource | Describe a datasource the way the report builder sees it, in one call: its data views, the advanced settings each view requires, its default view and defaults, and its metric and dimension… |
link_datasource | Point a client at one of the account’s datasource connections — the connect panel’s account picker, as a tool. Call it with just client_id + datasource_id to see the choices, then again with… |
rename_connection | Rename a datasource connection |
test_connection | Test whether a stored datasource connection is still working (e.g. the OAuth token is valid). Records the outcome on the connection, so its status reflects this test. |
unlink_datasource 🔒 | Detach a connected datasource from a client so its widgets no longer pull from that connection. Does not delete the connection itself. The affected widgets keep their config and fall back to… |
Domains
| Tool | What it does |
|---|---|
add_domain | Add a custom domain. The backend detects the DNS provider and returns the DNS records the user needs to configure. |
list_domains | List custom domains registered on the account, including DNS verification records |
remove_domain 🔒 | Remove a custom domain by its ID |
| Tool | What it does |
|---|---|
list_email_senders | List configured “From” senders and the active provider. |
list_email_templates | List reusable email templates. |
set_default_email_sender | Make a sender the account default. |
set_default_email_template | Make an email template the account default. |
Exports
| Tool | What it does |
|---|---|
archive_export 🔒 | Archive a PDF export record by ID. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
list_exports | List PDF export history for a report (one row per generation attempt). |
Folders
| Tool | What it does |
|---|---|
create_folder | Create a new client folder |
delete_folder 🔒 | Delete a client folder |
list_folders | List all client folders for the account |
update_folder | Rename a client folder |
Goals
| Tool | What it does |
|---|---|
archive_goal 🔒 | Archive a goal by ID. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
create_goal | Create a goal — a target value + comparison for a saved metric query. |
duplicate_goal | Duplicate a goal, optionally with a new name. |
list_goals | List goals for the account (targets tracked against a metric query). |
update_goal | Update a goal — only include the fields you want to change. |
Media
| Tool | What it does |
|---|---|
archive_media_file 🔒 | Archive a media file. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. The file itself is only removed from storage when it is permanently de… |
archive_media_files 🔒 | Archive several media files by ID in one call. They go to the archive, not away — list_archive shows them and restore_from_archive brings them back. |
list_media | List media files |
rename_media_file | Rename a media file |
Pages
| Tool | What it does |
|---|---|
create_page | Add a page to a report or template. Appended at the end by default. |
delete_page 🔒 | Delete a page by ID |
list_pages | List the pages of a report or dashboard, ordered by position. For a template, use list_template_pages. |
list_template_pages | List the pages of a template, ordered by position. |
update_page | Update a page — only include the fields you want to change |
| Tool | What it does |
|---|---|
generate_pdf | Queue a PDF render of a report or dashboard. Returns a job_id — poll get_pdf_status until it completes, then download the URL. A multi-page report prints page by page; a dashboard prints as one long page. |
get_pdf_status | Poll a PDF job with the job_id generate_pdf returned. status is processing → complete (with a url) or failed. |
Reports
| Tool | What it does |
|---|---|
archive_report 🔒 | Archive a report by ID. Its pages and widgets stay attached and come back with it. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
archive_reports 🔒 | Archive several reports by ID in one call. They go to the archive, not away — list_archive shows them and restore_from_archive brings them back. |
change_report_date_range | Set the period a report covers. Every data widget on it is re-fetched for the new range and the results are saved — widgets on their own custom range keep it. A rolling preset (“Last 30 Days… |
create_report | Create a new report or dashboard for a client. Presentation toggles have server defaults when omitted. A report is created on the grid layout or the free canvas; a dashboard is always grid. |
duplicate_report | Duplicate a report with a new name |
get_report | Get a single report by ID |
list_reports | List reports and dashboards for the account, optionally filtered by client. |
preview_report | Show a report as the client sees it — the live page, rendered in the conversation. Use this after building or changing one, and to check layout: overlapping widgets, spacing, cut-off heading… |
refresh_report | Re-fetch every data widget on a report with its current config and the report date range, saving the results. Pass datasource_id to refresh only the widgets fed by one datasource — what you… |
update_report | Update a report — only include the fields you want to change |
Search
| Tool | What it does |
|---|---|
search | Search clients and reports by name (minimum 2 characters) |
Templates
| Tool | What it does |
|---|---|
archive_template 🔒 | Archive a template by ID. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
create_template | Create a template from an existing report. Pages, widgets, and datasource categories are copied/derived from the source report automatically. |
get_template | Get a single template by ID |
list_template_widgets | List the widgets that belong to a template (optionally filtered to a single page). |
list_templates | List report templates with optional filtering and pagination |
update_template | Update a template — only include the fields you want to change |
Themes
| Tool | What it does |
|---|---|
archive_theme 🔒 | Archive a theme by ID. Reports using it fall back to the default. It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back. |
create_theme | Create a new visual theme. Supply the complete tokens map (primary, font, radius, shadow, canvas, surface, chart1-10, etc.) — tokens are the single source of truth for every visual property.… |
get_theme | Get a single theme by ID |
list_themes | List all themes available to the account (own + shared) |
update_theme | Update a theme — only include the fields you want to change. Supply the full tokens map when changing visual properties (partial token updates replace the entire map). Update cover_page or t… |
Users
| Tool | What it does |
|---|---|
get_current_user | Get the currently authenticated user profile |
invite_user 🔒 | Invite a new user to join the account. admin has full account access; clients gives read+write to assigned clients; readonly is view-only on assigned clients. |
list_users | List all team members on the account |
remove_user 🔒 | Remove a team member from the account |
update_my_avatar | Update the authenticated user’s profile picture |
update_my_profile | Update the authenticated user’s profile — only include the fields you want to change |
update_user | Edit a team member — only include the fields you want to change |
Widgets
| Tool | What it does |
|---|---|
add_button_widget | Add a button widget to a page. Position, width, and height use sensible defaults. |
add_calculated_metric_widget | Add a Calculated Metric widget to a page: a table trended by date, showing demo data until it points at a formula. Returns the new widget_id — point it at a formula with update_calculated_me… |
add_custom_data_widget | Add a Custom Data widget to a page: a table showing demo data until it points at an uploaded CSV dataset. Returns the new widget_id — point it at a dataset with update_custom_data_widget, us… |
add_data_widget | Add a DATA widget to a page and configure it, applying the same rules as the report builder: the datasource’s defaults, the generated name, sort and row limit, and validation of the metric/d… |
add_embed_widget | Add an embed widget to a page. Position, width, and height use sensible defaults. |
add_goal_widget | Add a Goal widget to a page: a progress gauge showing a demo target until it points at a saved goal. Returns the new widget_id — point it at a goal with update_goal_widget, using an id from… |
add_image_widget | Add an image widget to a page. Position, width, and height use sensible defaults. |
add_static_value_widget | Add a Static Value widget to a page: one typed-in value as a KPI card — a number, an amount like “R50”, or free text like “Active”. It has no datasource and never fetches, so unlike the othe… |
add_text_widget | Add a rich-text widget to a page. The body accepts Markdown. Position, width, and height use sensible defaults. |
add_title_widget | Add a title widget to a page. Position, width, and height use sensible defaults. |
datasource_resources | List the selectable values behind a widget’s advanced settings and filters — campaigns, ad sets, forms, videos, alerts, and so on. describe_datasource says WHICH advanced keys a data view re… |
delete_widget 🔒 | Delete a widget by ID. |
delete_widgets 🔒 | Delete multiple widgets by ID in one call. |
get_widget | Get a single widget by ID. |
get_widget_data | Read the numbers behind data widgets, for charting them. Requires one of: widget_ids for specific widgets, or source_id for every data widget on a report. Returns one entry per widget: its n… |
list_widgets | List all widgets on a report or dashboard. For a template, use list_template_widgets. |
move_widget | Move or resize a widget. Works for any widget type. Pass only the dimensions you want to change. |
query_data | Pull live metric values from a client’s connected datasource for any date range, without touching a report. Nothing is saved — use this for ad-hoc analysis and period comparisons. To read th… |
refresh_widgets | Re-fetch specific widgets with their saved config and save the results. Configuring a widget with update_data_widget already refreshes it, so this is for re-reading without a config change.… |
update_button_widget | Update a BUTTON widget. |
update_calculated_metric_widget | Point a Calculated Metric widget at a saved formula. Ids come from list_calculated_metrics. The series is re-fetched in the background — call get_widget_data with this id to read the numbers… |
update_custom_data_widget | Point a Custom Data widget at an uploaded CSV dataset and choose its columns. The dataset id comes from list_custom_data and the column names from get_custom_data — a dataset has no fixed ca… |
update_data_widget | Update a DATA widget — its name, datasource, data view, metrics, dimensions, filters, advanced settings, chart type, date range, sort and row limit. Applies the report builder’s rules: a new… |
update_embed_widget | Update an EMBED widget. |
update_goal_widget | Point a Goal widget at a saved goal. Ids come from list_goals. The goal carries its own metric query, target and comparison, so nothing else is needed; the gauge is re-fetched in the backgro… |
update_image_widget | Update an IMAGE widget. |
update_static_value_widget | Set the value on a Static Value widget — a number, an amount like “R50”, or free text like “Active”. It has no datasource and never fetches, so the value is shown exactly as passed. |
update_text_widget | Update a TEXT widget — an executive summary, commentary, any prose block. The body accepts Markdown. Replaces the entire text content. |
update_title_widget | Update a TITLE widget. |
Workflows
| Tool | What it does |
|---|---|
audit_report_health | Audit a report or dashboard: list its connected data sources and automation state, and flag likely issues (no data sources connected, paused automations). Read-only. |
create_client_with_report | Create a new client and its first report or dashboard in one step. The first report is resolved from the inputs: template_id clones that template; blank:true creates an empty report; with ne… |
create_report_from_template | Create a report or dashboard for an existing client by cloning a template (its pages + widgets). Find the template first with list_templates — filter by datasources + type (e.g. datasources=… |
Conventions
- Identifiers — calls return IDs the agent chains into later calls. It is instructed to refer to records by name in chat, never by ID.
- Multi-tenancy — every call is scoped to the authenticated account. You never pass an
account_id. - Discovery first —
datasources, thendescribe_datasource, before configuring a data widget: the second returns that datasource’s data views, metrics, dimensions and required settings. - Metrics and dimensions are objects — pass
[{ "value": "clicks" }], not["clicks"]. Onlyvalueis required; Oviond fills in the rest from the catalog. The same shape is used by the widget, goal and calculated-metric tools. - One tool per widget type —
add_data_widgetfor a datasource-backed widget, andadd_calculated_metric_widget,add_custom_data_widget,add_goal_widgetandadd_static_value_widgetfor the four sources that aren’t a platform. Each takes only the fields its type has, and each has a matchingupdate_tool. - Data is fetched server-side after a widget is written.
refresh_widgetsorrefresh_reportforce it. Reading it back isget_widget_data, which waits briefly for in-flight fetches and returns each widget’s state plus its rows — up to 200 per widget. query_datais the read-only way to pull figures. It returns live metric values for any date range straight from the client’s connected datasource and saves nothing, so it works on a read-only connection — unlikerefresh_widgets, which writes the results back onto the report and a read-only client will rightly decline. Useget_widget_datato read what a report already holds, andquery_datafor ad-hoc analysis and period comparisons.